My Articles On JavaCodeGeeks

These articles are re-published by JavaCodeGeeks.com. It’s a awesome resource for Java developers, I highly recommend to read me there :)

badge

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Don't Use Java Assertions </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/06/17/dont-use-java-assertions.html>12 Best</li> <li /2016/06/17/dont-use-java-assertions.html>All 292</li> <li /2016/06/17/dont-use-java-assertions.html>Webinars</li> <li /2016/06/17/dont-use-java-assertions.html>Talks</li> <li /2016/06/17/dont-use-java-assertions.html>Books</li> <li /2016/06/17/dont-use-java-assertions.html>Papers</li> <li /2016/06/17/dont-use-java-assertions.html>Pets</li> <li /2016/06/17/dont-use-java-assertions.html class=”highlighted”>Trainings</li> <li /2016/06/17/dont-use-java-assertions.html>Award</li> <li /2016/06/17/dont-use-java-assertions.html>Testimonials</li> <li /2016/06/17/dont-use-java-assertions.html>Shift-M</li> <li /2016/06/17/dont-use-java-assertions.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Don’t Use Java Assertions</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Los Angeles, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>There are basically two ways to validate a situation in Java and complain when something unexpected happens. It’s either an exception or an assertion. Technically, they are almost the same, but there are some small differences. I believe that exceptions are the right way to go in all situations and assertions should never be used. Here’s why.</p>

Natural Born Killers (1994) by Oliver Stone<figcaption id="44ce340c">Natural Born Killers (1994) by Oliver Stone</figcaption>
<p>Let’s see what happens when an assertion is triggered. Say that this is our code:</p>
<pre>public class Main { public static void main(String... args) { assert true == false : "There is a problem"; System.out.println("Hello, world!"); } }</pre>
<p>Save this code to Main.java and compile:</p>
<pre>$ javac Main.java</pre>
<p>Then run it:</p>
<pre>$ java Main Hello, world!</pre>
<p>The assertion wasn’t triggered. It was ignored. Now run it with an -enableassertions flag:</p>
<pre>$ java -enableassertions Main Exception in thread "main" java.lang.AssertionError: There is a problem at Main.main(Main.java:3)</pre>
<p>This is the first difference between exceptions and assertions. Exceptions will always be thrown, while assertions are not enabled by default. They are supposed to be turned on during testing and turned off in production. The assertion caused the runtime exception AssertionError. But hold on; it’s not a RuntimeException. It extends Error class, which extends Throwable. This is the second difference. I don’t know of any other differences.</p><p>I would recommend not to use assertions … ever. Simply because I strongly believe in the Fail Fast approach. I think bugs must be visible not only during testing but also in production. Moreover, I believe making bugs visible in production is very important if you want to achieve a high-quality product.</p><p>Thus, no assertions. They are simply a flawed and outdated feature in Java (and some other languages).</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>There are basically two ways to validate a situation in Java and complain when something unexpected happens. It’s either an exception or an assertion. Technically, they are almost the same, but there are some small differences. I believe that exceptions are the right way to go in all situations and assertions should never be used. Here’s why.</p>
Natural Born Killers (1994) by Oliver Stone<figcaption id="44ce340c">Natural Born Killers (1994) by Oliver Stone</figcaption>
<p>Let’s see what happens when an assertion is triggered. Say that this is our code:</p>
<pre>public class Main { public static void main(String... args) { assert true == false : "There is a problem"; System.out.println("Hello, world!"); } }</pre>
<p>Save this code to Main.java and compile:</p>
<pre>$ javac Main.java</pre>
<p>Then run it:</p>
<pre>$ java Main Hello, world!</pre>
<p>The assertion wasn’t triggered. It was ignored. Now run it with an -enableassertions flag:</p>
<pre>$ java -enableassertions Main Exception in thread "main" java.lang.AssertionError: There is a problem at Main.main(Main.java:3)</pre>
<p>This is the first difference between exceptions and assertions. Exceptions will always be thrown, while assertions are not enabled by default. They are supposed to be turned on during testing and turned off in production. The assertion caused the runtime exception AssertionError. But hold on; it’s not a RuntimeException. It extends Error class, which extends Throwable. This is the second difference. I don’t know of any other differences.</p><p>I would recommend not to use assertions … ever. Simply because I strongly believe in the Fail Fast approach. I think bugs must be visible not only during testing but also in production. Moreover, I believe making bugs visible in production is very important if you want to achieve a high-quality product.</p><p>Thus, no assertions. They are simply a flawed and outdated feature in Java (and some other languages).</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Test Methods Must Share Nothing </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/05/03/test-methods-must-share-nothing.html>12 Best</li> <li /2016/05/03/test-methods-must-share-nothing.html>All 292</li> <li /2016/05/03/test-methods-must-share-nothing.html>Webinars</li> <li /2016/05/03/test-methods-must-share-nothing.html>Talks</li> <li /2016/05/03/test-methods-must-share-nothing.html>Books</li> <li /2016/05/03/test-methods-must-share-nothing.html>Papers</li> <li /2016/05/03/test-methods-must-share-nothing.html>Pets</li> <li /2016/05/03/test-methods-must-share-nothing.html class=”highlighted”>Trainings</li> <li /2016/05/03/test-methods-must-share-nothing.html>Award</li> <li /2016/05/03/test-methods-must-share-nothing.html>Testimonials</li> <li /2016/05/03/test-methods-must-share-nothing.html>Shift-M</li> <li /2016/05/03/test-methods-must-share-nothing.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Test Methods Must Share Nothing</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Constants… I wrote about them some time ago, mostly saying that they are a bad thing, if being public. They reduce duplication, but introduce coupling. A much better way to get rid of duplication is by creating new classes or methods—a traditional OOP method. This seems to make sense and in our projects I see less and less public constants. In some projects we don’t have them at all. But one thing still bothers me: unit tests. Most programmers seem to think that when static analysis says that there are too many similar literals in the same file, the best way to get rid of them is via a private static literal. This is just wrong.</p>
Oldeuboi (2003) by Chan-wook Park<figcaption id="934a9853">Oldeuboi (2003) by Chan-wook Park</figcaption>
<p>Unit tests, naturally, duplicate a lot of code. Test methods contain similar or almost identical functionality and this is almost inevitable. Well, we can use more of that @Before and @BeforeClass features, but sometimes it’s just not possible. We may have, say, 20 test methods in one FooTest.java file. Preparing all objects in one “before” is not possible. So we have to do certain things again and again in our test methods.</p><p>Let’s take a look at one of the classes in our Takes Framework: VerboseListTest. It’s a unit test and it has a problem, which I’m trying to tell you about. Look at that MSG private literal. It is used for the first time in setUp() method as an argument of an object constructor and then in a few test methods to check how that object behaves. Let me simplify that code:</p>
<pre>class FooTest { private static final String MSG = "something"; @Before public final void setUp() throws Exception { this.foo = new Foo(FooTest.MSG); } @Test public void simplyWorks() throws IOException { assertThat( foo.doSomething(), containsString(FooTest.MSG) ); } @Test public void simplyWorksAgain() throws IOException { assertThat( foo.doSomethingElse(), containsString(FooTest.MSG) ); } }</pre>
<p>This is basically what is happening in VerboseListTest and it’s very wrong. Why? Because this shared literal MSG introduced an unnatural coupling between these two test methods. They have nothing in common, because they test different behaviors of class Foo. But this private constant ties them together. Now they are somehow related.</p><p>If and when I want to modify one of the test methods, I may need to modify the other one too. Say I want to see how doSomethingElse() behaves if the encapsulated message is an empty string. What do I do? I change the value of the constant FooTest.MSG, which is used by another test method. This is called coupling. And it’s a bad thing.</p><p>What do we do? Well, we can use that "something" string literal in both test methods:</p>
<pre>class FooTest { @Test public void simplyWorks() throws IOException { assertThat( new Foo("something").doSomething(), containsString("something") ); } @Test public void simplyWorksAgain() throws IOException { assertThat( new Foo("something").doSomethingElse(), containsString("something") ); } }</pre>
<p>As you see, I got rid of that setUp() method and the private static literal MSG. What do we have now? Code duplication. String "something" shows up four times in the test class. No static analyzers will tolerate that. Moreover, there are seven (!) test methods in VerboseListTest, which are using MSG. Thus, we will have 14 occurrences of "something", right? Yes, that’s right and that’s most likely why one of authors of this test case introduced the constant—to get rid of duplication. BTW, @Happy-Neko did that in pull request #513, @carlosmiranda reviewed the code and I approved the changes. So, three people made/approved that mistake, including myself.</p><p>So what is the right approach that will avoid code duplication and at the same time won’t introduce coupling? Here it is:</p>
<pre>class FooTest { @Test public void simplyWorks() throws IOException { final String msg = "something"; assertThat( new Foo(msg).doSomething(), containsString(msg) ); } @Test public void simplyWorksAgain() throws IOException { final String msg = "something else"; assertThat( new Foo(msg).doSomethingElse(), containsString(msg) ); } }</pre>
<p>These literals must be different. This is what any static analyzer is saying when it sees "something" in so many places. It questions us—why are they the same? Is it really so important to use "something" everywhere? Why can’t you use different literals? Of course we can. And we should.</p><p>The bottom line is that each test method must have its own set of data and objects. They must not be shared between test methods ever. Test methods must always be independent, having nothing in common.</p><p>Having that in mind, we can easily conclude that methods like setUp() or any shared variables in test classes are evil. They must not be used and simply must not exist. I think that their invention in JUnit caused a lot of harm to Java code.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Constants… I wrote about them some time ago, mostly saying that they are a bad thing, if being public. They reduce duplication, but introduce coupling. A much better way to get rid of duplication is by creating new classes or methods—a traditional OOP method. This seems to make sense and in our projects I see less and less public constants. In some projects we don’t have them at all. But one thing still bothers me: unit tests. Most programmers seem to think that when static analysis says that there are too many similar literals in the same file, the best way to get rid of them is via a private static literal. This is just wrong.</p>
Oldeuboi (2003) by Chan-wook Park<figcaption id="934a9853">Oldeuboi (2003) by Chan-wook Park</figcaption>
<p>Unit tests, naturally, duplicate a lot of code. Test methods contain similar or almost identical functionality and this is almost inevitable. Well, we can use more of that @Before and @BeforeClass features, but sometimes it’s just not possible. We may have, say, 20 test methods in one FooTest.java file. Preparing all objects in one “before” is not possible. So we have to do certain things again and again in our test methods.</p><p>Let’s take a look at one of the classes in our Takes Framework: VerboseListTest. It’s a unit test and it has a problem, which I’m trying to tell you about. Look at that MSG private literal. It is used for the first time in setUp() method as an argument of an object constructor and then in a few test methods to check how that object behaves. Let me simplify that code:</p>
<pre>class FooTest { private static final String MSG = "something"; @Before public final void setUp() throws Exception { this.foo = new Foo(FooTest.MSG); } @Test public void simplyWorks() throws IOException { assertThat( foo.doSomething(), containsString(FooTest.MSG) ); } @Test public void simplyWorksAgain() throws IOException { assertThat( foo.doSomethingElse(), containsString(FooTest.MSG) ); } }</pre>
<p>This is basically what is happening in VerboseListTest and it’s very wrong. Why? Because this shared literal MSG introduced an unnatural coupling between these two test methods. They have nothing in common, because they test different behaviors of class Foo. But this private constant ties them together. Now they are somehow related.</p><p>If and when I want to modify one of the test methods, I may need to modify the other one too. Say I want to see how doSomethingElse() behaves if the encapsulated message is an empty string. What do I do? I change the value of the constant FooTest.MSG, which is used by another test method. This is called coupling. And it’s a bad thing.</p><p>What do we do? Well, we can use that "something" string literal in both test methods:</p>
<pre>class FooTest { @Test public void simplyWorks() throws IOException { assertThat( new Foo("something").doSomething(), containsString("something") ); } @Test public void simplyWorksAgain() throws IOException { assertThat( new Foo("something").doSomethingElse(), containsString("something") ); } }</pre>
<p>As you see, I got rid of that setUp() method and the private static literal MSG. What do we have now? Code duplication. String "something" shows up four times in the test class. No static analyzers will tolerate that. Moreover, there are seven (!) test methods in VerboseListTest, which are using MSG. Thus, we will have 14 occurrences of "something", right? Yes, that’s right and that’s most likely why one of authors of this test case introduced the constant—to get rid of duplication. BTW, @Happy-Neko did that in pull request #513, @carlosmiranda reviewed the code and I approved the changes. So, three people made/approved that mistake, including myself.</p><p>So what is the right approach that will avoid code duplication and at the same time won’t introduce coupling? Here it is:</p>
<pre>class FooTest { @Test public void simplyWorks() throws IOException { final String msg = "something"; assertThat( new Foo(msg).doSomething(), containsString(msg) ); } @Test public void simplyWorksAgain() throws IOException { final String msg = "something else"; assertThat( new Foo(msg).doSomethingElse(), containsString(msg) ); } }</pre>
<p>These literals must be different. This is what any static analyzer is saying when it sees "something" in so many places. It questions us—why are they the same? Is it really so important to use "something" everywhere? Why can’t you use different literals? Of course we can. And we should.</p><p>The bottom line is that each test method must have its own set of data and objects. They must not be shared between test methods ever. Test methods must always be independent, having nothing in common.</p><p>Having that in mind, we can easily conclude that methods like setUp() or any shared variables in test classes are evil. They must not be used and simply must not exist. I think that their invention in JUnit caused a lot of harm to Java code.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Why InputStream Design Is Wrong </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>12 Best</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>All 292</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Webinars</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Talks</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Books</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Papers</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Pets</li> <li /2016/04/26/why-inputstream-design-is-wrong.html class=”highlighted”>Trainings</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Award</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Testimonials</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Shift-M</li> <li /2016/04/26/why-inputstream-design-is-wrong.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Why InputStream Design Is Wrong</h1><aside class='book'>book coverRead more about this subject in Section 2.9
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Washington, D.C.</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>It’s not just about InputSteam, this class is a good example of a bad design. I’m talking about three overloaded methods read(). I’ve mentioned this problem in Section 2.9 of Elegant Objects. In a few words, I strongly believe that interfaces must be “functionality poor.” InputStream should have been an interface in the first place and it should have had a single method read(byte[]). Then if its authors wanted to give us extra functionality, they should have created supplementary “smart” classes.</p>
A Serious Man (2009) by Coen Brothers<figcaption id="490f983a">A Serious Man (2009) by Coen Brothers</figcaption>
<p>This is how it looks now:</p>
<pre>abstract class InputStream { int read(); int read(byte[] buffer, int offset, int length); int read(byte[] buffer); }</pre>
<p>What’s wrong? It’s very convenient to have the ability to read a single byte, an array of bytes or even an array of bytes with a direct positioning into a specific place in the buffer!</p><aside class="youtube"> <div class="box"> YouTube video #Xk9tIqwca3k<div class="play"></div></div><div>Smart Classes and Functionality-Poor Interfaces (webinar #16); 7 July 2016.</div></aside><p>However, we are still lacking a few methods: for reading the bytes and immediately saving into a file, converting to a text with a selected encoding, sending them by email and posting on Twitter. It would be great to have the features too, right in the poor InputStream. I hope the Oracle Java team is working on them now.</p><p>In the mean time, let’s see what exactly is wrong with what these bright engineers designed for us already. Or maybe let me show how I would design InputStream and we’ll compare:</p>
<pre>interface InputStream { int read(byte[] buffer, int offset, int length); }</pre>
<p>This is my design. The InputStream is responsible for reading bytes from the stream. There is one single method for this feature. Is it convenient for everybody? Does it read and post on Twitter? Not yet. Do we need that functionality? Of course we do, but it doesn’t mean that we will add it to the interface. Instead, we will create supplementary “smart” class:</p>
<pre>interface InputStream { int read(byte[] buffer, int offset, int length); class Smart { private final InputStream origin; public Smart(InputStream stream) { this.origin = stream; } public int read() { final byte[] buffer = new byte[1]; final int read = this.origin.read(buffer, 0, 1); final int result; if (read < 1) { result = -1; } else { result = buffer[0]; } return result; } } }</pre>
<p>Now, we want to read a single byte from the stream. Here is how:</p>
<pre>final InputStream input = new FileInputStream("/tmp/a.txt"); final byte b = new InputStream.Smart(input).read();</pre>
<p>The functionality of reading a single byte is outside of InputStream, because this is not its business. The stream doesn’t need to know how to manage the data after it is read. All the stream is responsible for is reading, not parsing or manipulating afterwards.</p><p>Interfaces must be small.</p><p>Obviously, method overloading in interfaces is a code smell. An interface with more than three methods is a good candidate for refactoring. If methods overload each other—it’s serious trouble.</p><p>Interfaces must be small!</p><p>You may say that the creators of InputStream cared about performance, that’s why allowed us to implement read() in three different forms. Then I have to ask again, why not create a method for reading and immediately post it on Twitter? That would be fantastically fast. Isn’t it what we all want? A fast software which nobody has any desire to read or maintain.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>It’s not just about InputSteam, this class is a good example of a bad design. I’m talking about three overloaded methods read(). I’ve mentioned this problem in Section 2.9 of Elegant Objects. In a few words, I strongly believe that interfaces must be “functionality poor.” InputStream should have been an interface in the first place and it should have had a single method read(byte[]). Then if its authors wanted to give us extra functionality, they should have created supplementary “smart” classes.</p>
A Serious Man (2009) by Coen Brothers<figcaption id="490f983a">A Serious Man (2009) by Coen Brothers</figcaption>
<p>This is how it looks now:</p>
<pre>abstract class InputStream { int read(); int read(byte[] buffer, int offset, int length); int read(byte[] buffer); }</pre>
<p>What’s wrong? It’s very convenient to have the ability to read a single byte, an array of bytes or even an array of bytes with a direct positioning into a specific place in the buffer!</p><aside class="youtube"> <div class="box"> YouTube video #Xk9tIqwca3k<div class="play"></div></div><div>Smart Classes and Functionality-Poor Interfaces (webinar #16); 7 July 2016.</div></aside><p>However, we are still lacking a few methods: for reading the bytes and immediately saving into a file, converting to a text with a selected encoding, sending them by email and posting on Twitter. It would be great to have the features too, right in the poor InputStream. I hope the Oracle Java team is working on them now.</p><p>In the mean time, let’s see what exactly is wrong with what these bright engineers designed for us already. Or maybe let me show how I would design InputStream and we’ll compare:</p>
<pre>interface InputStream { int read(byte[] buffer, int offset, int length); }</pre>
<p>This is my design. The InputStream is responsible for reading bytes from the stream. There is one single method for this feature. Is it convenient for everybody? Does it read and post on Twitter? Not yet. Do we need that functionality? Of course we do, but it doesn’t mean that we will add it to the interface. Instead, we will create supplementary “smart” class:</p>
<pre>interface InputStream { int read(byte[] buffer, int offset, int length); class Smart { private final InputStream origin; public Smart(InputStream stream) { this.origin = stream; } public int read() { final byte[] buffer = new byte[1]; final int read = this.origin.read(buffer, 0, 1); final int result; if (read < 1) { result = -1; } else { result = buffer[0]; } return result; } } }</pre>
<p>Now, we want to read a single byte from the stream. Here is how:</p>
<pre>final InputStream input = new FileInputStream("/tmp/a.txt"); final byte b = new InputStream.Smart(input).read();</pre>
<p>The functionality of reading a single byte is outside of InputStream, because this is not its business. The stream doesn’t need to know how to manage the data after it is read. All the stream is responsible for is reading, not parsing or manipulating afterwards.</p><p>Interfaces must be small.</p><p>Obviously, method overloading in interfaces is a code smell. An interface with more than three methods is a good candidate for refactoring. If methods overload each other—it’s serious trouble.</p><p>Interfaces must be small!</p><p>You may say that the creators of InputStream cared about performance, that’s why allowed us to implement read() in three different forms. Then I have to ask again, why not create a method for reading and immediately post it on Twitter? That would be fantastically fast. Isn’t it what we all want? A fast software which nobody has any desire to read or maintain.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Object Behavior Must Not Be Configurable </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/04/19/object-must-not-be-configurable.html>12 Best</li> <li /2016/04/19/object-must-not-be-configurable.html>All 292</li> <li /2016/04/19/object-must-not-be-configurable.html>Webinars</li> <li /2016/04/19/object-must-not-be-configurable.html>Talks</li> <li /2016/04/19/object-must-not-be-configurable.html>Books</li> <li /2016/04/19/object-must-not-be-configurable.html>Papers</li> <li /2016/04/19/object-must-not-be-configurable.html>Pets</li> <li /2016/04/19/object-must-not-be-configurable.html class=”highlighted”>Trainings</li> <li /2016/04/19/object-must-not-be-configurable.html>Award</li> <li /2016/04/19/object-must-not-be-configurable.html>Testimonials</li> <li /2016/04/19/object-must-not-be-configurable.html>Shift-M</li> <li /2016/04/19/object-must-not-be-configurable.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Object Behavior Must Not Be Configurable</h1><aside class='book'>book coverRead more about this subject in Section 5.5
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">New York, NY</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Using object properties as configuration parameters is a very common mistake we keep making mostly because our objects are mutable—we configure them. We change their behavior by injecting parameters or even entire settings/configuration objects into them. Do I have to say that it’s abusive and disrespectful from a philosophical point of view? I can, but let’s take a look at it from a practical perspective.</p>
The Take (2009) by David Drury<figcaption id="b28b6a76">The Take (2009) by David Drury</figcaption>
<p>Let’s say there is a class that is supposed to read a web page and return its content:</p>
<pre>class Page { private final String uri; Page(final String address) { this.uri = address; } public String html() throws IOException { return IOUtils.toString( new URL(this.uri).openStream(), "UTF-8" ); } }</pre>
<p>Looks simple and straight-forward, right? Yes, it’s a rather cohesive and solid class. Here is how we use it to read the content of Google front page:</p>
<pre>String html = new Page("http://www.google.com").html();</pre>
<p>Everything is fine until we start making this class more powerful. Let’s say we want to configure the encoding. We don’t always want to use "UTF-8". We want it to be configurable. Here is what we do:</p>
<pre>class Page { private final String uri; private final String encoding; Page(final String address, final String enc) { this.uri = address; this.encoding = enc; } public String html() throws IOException { return IOUtils.toString( new URL(this.uri).openStream(), this.encoding ); } }</pre>
<p>Done, the encoding is encapsulated and configurable. Now, let’s say we want to change the behavior of the class for the situation of an empty page. If an empty page is loaded, we want to return "<html/>". But not always. We want this to be configurable. Here is what we do:</p>
<pre>class Page { private final String uri; private final String encoding; private final boolean alwaysHtml; Page(final String address, final String enc, final boolean always) { this.uri = address; this.encoding = enc; this.alwaysHtml = always; } public String html() throws IOException { String html = IOUtils.toString( new URL(this.uri).openStream(), this.encoding ); if (html.isEmpty() && this.alwaysHtml) { html = "<html/>"; } return html; } }</pre>
<p>The class is getting bigger, huh? It’s great, we’re good programmers and our code must be complex, right? The more complex it is, the better programmers we are! I’m being sarcastic. Definitely not! But let’s move on. Now we want our class to proceed anyway, even if the encoding is not supported on the current platform:</p>
<pre>class Page { private final String uri; private final String encoding; private final boolean alwaysHtml; private final boolean encodeAnyway; Page(final String address, final String enc, final boolean always, final boolean encode) { this.uri = address; this.encoding = enc; this.alwaysHtml = always; this.encodeAnyway = encode; } public String html() throws IOException, UnsupportedEncodingException { final byte[] bytes = IOUtils.toByteArray( new URL(this.uri).openStream() ); String html; try { html = new String(bytes, this.encoding); } catch (UnsupportedEncodingException ex) { if (!this.encodeAnyway) { throw ex; } html = new String(bytes, "UTF-8") } if (html.isEmpty() && this.alwaysHtml) { html = "<html/>"; } return html; } }</pre>
<p>The class is growing and becoming more and more powerful! Now it’s time to introduce a new class, which we will call PageSettings:</p>
<pre>class Page { private final String uri; private final PageSettings settings; Page(final String address, final PageSettings stts) { this.uri = address; this.settings = stts; } public String html() throws IOException { final byte[] bytes = IOUtils.toByteArray( new URL(this.uri).openStream() ); String html; try { html = new String(bytes, this.settings.getEncoding()); } catch (UnsupportedEncodingException ex) { if (!this.settings.isEncodeAnyway()) { throw ex; } html = new String(bytes, "UTF-8") } if (html.isEmpty() && this.settings.isAlwaysHtml()) { html = "<html/>"; } return html; } }</pre>
<p>Class PageSettings is basically a holder of parameters, without any behavior. It has getters, which give us access to the parameters: isEncodeAnyway(), isAlwaysHtml(), and getEncoding(). If we keep going in this direction, there could be a few dozen configuration settings in that class. This may look very convenient and is a very typical pattern in Java world. For example, look at JobConf from Hadoop. This is how we will call our highly configurable Page (I’m assuming PageSettings is immutable):</p>
<pre>String html = new Page( "http://www.google.com", new PageSettings() .withEncoding("ISO_8859_1") .withAlwaysHtml(true) .withEncodeAnyway(false) ).html();</pre>
<p>However, no matter how convenient it may look at first glance, this approach is very wrong. Mostly because it encourages us to make big and non-cohesive objects. They grow in size and become less testable, less maintainable and less readable.</p><aside class="quote">Encapsulated properties must not be used to change the behavior of an object</aside><p>To prevent that from happening, I would suggest a simple rule here: object behavior should not be configurable. Or, more technically, encapsulated properties must not be used to change the behavior of an object.</p><p>Object properties are there only to coordinate the location of a real-world entity, which the object is representing. The uri is the coordinate, while the alwaysHtml boolean property is a behavior changing trigger. See the difference?</p><p>So, what should we do instead? What is the right design? We must use composable decorators. Here is how:</p>
<pre>Page page = new NeverEmptyPage( new DefaultPage("http://www.google.com") ) String html = new AlwaysTextPage( new TextPage(page, "ISO_8859_1") page ).html();</pre>
<p>Here is how our DefaultPage would look (yes, I had to change its design a bit):</p>
<pre>class DefaultPage implements Page { private final String uri; DefaultPage(final String address) { this.uri = address; } @Override public byte[] html() throws IOException { return IOUtils.toByteArray( new URL(this.uri).openStream() ); } }</pre>
<p>As you see, I’m making it implement interface Page. Now TextPage decorator, which converts an array of bytes to a text using provided encoding:</p>
<pre>class TextPage { private final Page origin; private final String encoding; TextPage(final Page page, final String enc) { this.origin = page; this.encoding = enc; } public String html() throws IOException { return new String( this.origin.html(), this.encoding ); } }</pre>
<p>Now the NeverEmptyPage:</p>
<pre>class NeverEmptyPage implements Page { private final Page origin; NeverEmptyPage(final Page page) { this.origin = page; } @Override public byte[] html() throws IOException { byte[] bytes = this.origin.html(); if (bytes.length == 0) { bytes = "<html/>".getBytes(); } return bytes; } }</pre>
<p>And finally the AlwaysTextPage:</p>
<pre>class AlwaysTextPage { private final TextPage origin; private final Page source; AlwaysTextPage(final TextPage page, final Page src) { this.origin = page; this.source = src; } public String html() throws IOException { String html; try { html = this.origin.html(); } catch (UnsupportedEncodingException ex) { html = new TextPage(this.source, "UTF-8").html(); } return html; } }</pre>
<p>You may say that AlwaysTextPage will make two calls to the encapsulated origin, in case of an unsupported encoding, which will lead to a duplicated HTTP request. That’s true and this is by design. We don’t want this duplicated HTTP roundtrip to happen. Let’s introduce one more class, which will cache the page fetched ( not thread-safe, but it’s not important now):</p>
<pre>class OncePage implements Page { private final Page origin; private final AtomicReference<byte[]> cache = new AtomicReference<>; OncePage(final Page page) { this.origin = page; } @Override public byte[] html() throws IOException { if (this.cache.get() == null) { this.cache.set(this.origin.html()); } return this.cache.get(); } }</pre>
<p>Now, our code should look like this (pay attention, I’m now using OncePage):</p>
<pre>Page page = new NeverEmptyPage( new OncePage( new DefaultPage("http://www.google.com") ) ) String html = new AlwaysTextPage( new TextPage(page, "ISO_8859_1") "UTF-8" ).html();</pre>
<p>This is probably the most code-intensive post on this site so far, but I hope it’s readable and I managed to convey the idea. Now we have five classes, each of which is rather small, easy to read and easy to reuse.</p><p>Just follow the rule: never make classes configurable!</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Using object properties as configuration parameters is a very common mistake we keep making mostly because our objects are mutable—we configure them. We change their behavior by injecting parameters or even entire settings/configuration objects into them. Do I have to say that it’s abusive and disrespectful from a philosophical point of view? I can, but let’s take a look at it from a practical perspective.</p>
The Take (2009) by David Drury<figcaption id="b28b6a76">The Take (2009) by David Drury</figcaption>
<p>Let’s say there is a class that is supposed to read a web page and return its content:</p>
<pre>class Page { private final String uri; Page(final String address) { this.uri = address; } public String html() throws IOException { return IOUtils.toString( new URL(this.uri).openStream(), "UTF-8" ); } }</pre>
<p>Looks simple and straight-forward, right? Yes, it’s a rather cohesive and solid class. Here is how we use it to read the content of Google front page:</p>
<pre>String html = new Page("http://www.google.com").html();</pre>
<p>Everything is fine until we start making this class more powerful. Let’s say we want to configure the encoding. We don’t always want to use "UTF-8". We want it to be configurable. Here is what we do:</p>
<pre>class Page { private final String uri; private final String encoding; Page(final String address, final String enc) { this.uri = address; this.encoding = enc; } public String html() throws IOException { return IOUtils.toString( new URL(this.uri).openStream(), this.encoding ); } }</pre>
<p>Done, the encoding is encapsulated and configurable. Now, let’s say we want to change the behavior of the class for the situation of an empty page. If an empty page is loaded, we want to return "<html/>". But not always. We want this to be configurable. Here is what we do:</p>
<pre>class Page { private final String uri; private final String encoding; private final boolean alwaysHtml; Page(final String address, final String enc, final boolean always) { this.uri = address; this.encoding = enc; this.alwaysHtml = always; } public String html() throws IOException { String html = IOUtils.toString( new URL(this.uri).openStream(), this.encoding ); if (html.isEmpty() && this.alwaysHtml) { html = "<html/>"; } return html; } }</pre>
<p>The class is getting bigger, huh? It’s great, we’re good programmers and our code must be complex, right? The more complex it is, the better programmers we are! I’m being sarcastic. Definitely not! But let’s move on. Now we want our class to proceed anyway, even if the encoding is not supported on the current platform:</p>
<pre>class Page { private final String uri; private final String encoding; private final boolean alwaysHtml; private final boolean encodeAnyway; Page(final String address, final String enc, final boolean always, final boolean encode) { this.uri = address; this.encoding = enc; this.alwaysHtml = always; this.encodeAnyway = encode; } public String html() throws IOException, UnsupportedEncodingException { final byte[] bytes = IOUtils.toByteArray( new URL(this.uri).openStream() ); String html; try { html = new String(bytes, this.encoding); } catch (UnsupportedEncodingException ex) { if (!this.encodeAnyway) { throw ex; } html = new String(bytes, "UTF-8") } if (html.isEmpty() && this.alwaysHtml) { html = "<html/>"; } return html; } }</pre>
<p>The class is growing and becoming more and more powerful! Now it’s time to introduce a new class, which we will call PageSettings:</p>
<pre>class Page { private final String uri; private final PageSettings settings; Page(final String address, final PageSettings stts) { this.uri = address; this.settings = stts; } public String html() throws IOException { final byte[] bytes = IOUtils.toByteArray( new URL(this.uri).openStream() ); String html; try { html = new String(bytes, this.settings.getEncoding()); } catch (UnsupportedEncodingException ex) { if (!this.settings.isEncodeAnyway()) { throw ex; } html = new String(bytes, "UTF-8") } if (html.isEmpty() && this.settings.isAlwaysHtml()) { html = "<html/>"; } return html; } }</pre>
<p>Class PageSettings is basically a holder of parameters, without any behavior. It has getters, which give us access to the parameters: isEncodeAnyway(), isAlwaysHtml(), and getEncoding(). If we keep going in this direction, there could be a few dozen configuration settings in that class. This may look very convenient and is a very typical pattern in Java world. For example, look at JobConf from Hadoop. This is how we will call our highly configurable Page (I’m assuming PageSettings is immutable):</p>
<pre>String html = new Page( "http://www.google.com", new PageSettings() .withEncoding("ISO_8859_1") .withAlwaysHtml(true) .withEncodeAnyway(false) ).html();</pre>
<p>However, no matter how convenient it may look at first glance, this approach is very wrong. Mostly because it encourages us to make big and non-cohesive objects. They grow in size and become less testable, less maintainable and less readable.</p><aside class="quote">Encapsulated properties must not be used to change the behavior of an object</aside><p>To prevent that from happening, I would suggest a simple rule here: object behavior should not be configurable. Or, more technically, encapsulated properties must not be used to change the behavior of an object.</p><p>Object properties are there only to coordinate the location of a real-world entity, which the object is representing. The uri is the coordinate, while the alwaysHtml boolean property is a behavior changing trigger. See the difference?</p><p>So, what should we do instead? What is the right design? We must use composable decorators. Here is how:</p>
<pre>Page page = new NeverEmptyPage( new DefaultPage("http://www.google.com") ) String html = new AlwaysTextPage( new TextPage(page, "ISO_8859_1") page ).html();</pre>
<p>Here is how our DefaultPage would look (yes, I had to change its design a bit):</p>
<pre>class DefaultPage implements Page { private final String uri; DefaultPage(final String address) { this.uri = address; } @Override public byte[] html() throws IOException { return IOUtils.toByteArray( new URL(this.uri).openStream() ); } }</pre>
<p>As you see, I’m making it implement interface Page. Now TextPage decorator, which converts an array of bytes to a text using provided encoding:</p>
<pre>class TextPage { private final Page origin; private final String encoding; TextPage(final Page page, final String enc) { this.origin = page; this.encoding = enc; } public String html() throws IOException { return new String( this.origin.html(), this.encoding ); } }</pre>
<p>Now the NeverEmptyPage:</p>
<pre>class NeverEmptyPage implements Page { private final Page origin; NeverEmptyPage(final Page page) { this.origin = page; } @Override public byte[] html() throws IOException { byte[] bytes = this.origin.html(); if (bytes.length == 0) { bytes = "<html/>".getBytes(); } return bytes; } }</pre>
<p>And finally the AlwaysTextPage:</p>
<pre>class AlwaysTextPage { private final TextPage origin; private final Page source; AlwaysTextPage(final TextPage page, final Page src) { this.origin = page; this.source = src; } public String html() throws IOException { String html; try { html = this.origin.html(); } catch (UnsupportedEncodingException ex) { html = new TextPage(this.source, "UTF-8").html(); } return html; } }</pre>
<p>You may say that AlwaysTextPage will make two calls to the encapsulated origin, in case of an unsupported encoding, which will lead to a duplicated HTTP request. That’s true and this is by design. We don’t want this duplicated HTTP roundtrip to happen. Let’s introduce one more class, which will cache the page fetched ( not thread-safe, but it’s not important now):</p>
<pre>class OncePage implements Page { private final Page origin; private final AtomicReference<byte[]> cache = new AtomicReference<>; OncePage(final Page page) { this.origin = page; } @Override public byte[] html() throws IOException { if (this.cache.get() == null) { this.cache.set(this.origin.html()); } return this.cache.get(); } }</pre>
<p>Now, our code should look like this (pay attention, I’m now using OncePage):</p>
<pre>Page page = new NeverEmptyPage( new OncePage( new DefaultPage("http://www.google.com") ) ) String html = new AlwaysTextPage( new TextPage(page, "ISO_8859_1") "UTF-8" ).html();</pre>
<p>This is probably the most code-intensive post on this site so far, but I hope it’s readable and I managed to convey the idea. Now we have five classes, each of which is rather small, easy to read and easy to reuse.</p><p>Just follow the rule: never make classes configurable!</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Java Annotations Are a Big Mistake </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/04/12/java-annotations-are-evil.html>12 Best</li> <li /2016/04/12/java-annotations-are-evil.html>All 292</li> <li /2016/04/12/java-annotations-are-evil.html>Webinars</li> <li /2016/04/12/java-annotations-are-evil.html>Talks</li> <li /2016/04/12/java-annotations-are-evil.html>Books</li> <li /2016/04/12/java-annotations-are-evil.html>Papers</li> <li /2016/04/12/java-annotations-are-evil.html>Pets</li> <li /2016/04/12/java-annotations-are-evil.html class=”highlighted”>Trainings</li> <li /2016/04/12/java-annotations-are-evil.html>Award</li> <li /2016/04/12/java-annotations-are-evil.html>Testimonials</li> <li /2016/04/12/java-annotations-are-evil.html>Shift-M</li> <li /2016/04/12/java-annotations-are-evil.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Java Annotations Are a Big Mistake</h1><aside class='book'>book coverRead more about this subject in Section 6.1
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Seattle, WA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Annotations were introduced in Java 5, and we all got excited. Such a great instrument to make code shorter! No more Hibernate/Spring XML configuration files! Just annotations, right there in the code where we need them. No more marker interfaces, just a runtime-retained reflection-discoverable annotation! I was excited too. Moreover, I’ve made a few open source libraries which use annotations heavily. Take jcabi-aspects, for example. However, I’m not excited any more. Moreover, I believe that annotations are a big mistake in Java design.</p>
Gomorra (2008) by Matteo Garrone)<figcaption id="8ef9c86b">Gomorra (2008) by Matteo Garrone)</figcaption>
<aside class="youtube"> <div class="box"> YouTube video #g1ctRcW214w<div class="play"></div></div><div>Java Annotations Are a Big Mistake (webinar #14); 4 May 2016.</div></aside><p>Long story short, there is one big problem with annotations—they encourage us to implement object functionality outside of an object, which is against the very principle of encapsulation. The object is not solid any more, since its behavior is not defined entirely by its own methods—some of its functionality stays elsewhere. Why is it bad? Let’s see in a few examples.</p><h2 id="inject">@Inject</h2><p>Say we annotate a property with @Inject:</p>
<pre>import javax.inject.Inject; public class Books { @Inject private final DB db; // some methods here, which use this.db }</pre>
<p>Then we have an injector that knows what to inject:</p>
<pre>Injector injector = Guice.createInjector( new AbstractModule() { @Override public void configure() { this.bind(DB.class).toInstance( new Postgres("jdbc:postgresql:5740/main") ); } } );</pre>
<p>Now we’re making an instance of class Books via the container:</p>
<pre>Books books = injector.getInstance(Books.class);</pre>
<p>The class Books has no idea how and who will inject an instance of class DB into it. This will happen behind the scenes and outside of its control. The injection will do it. It may look convenient, but this attitude causes a lot of damage to the entire code base. The control is lost (not inverted, but lost!). The object is not in charge any more. It can’t be responsible for what’s happening to it.</p><p>Instead, here is how this should be done:</p>
<pre>class Books { private final DB db; Books(final DB base) { this.db = base; } // some methods here, which use this.db }</pre>
<p>This article explains why Dependency Injection containers are a wrong idea in the first place: Dependency Injection Containers are Code Polluters. Annotations basically provoke us to make the containers and use them. We move functionality outside of our objects and put it into containers, or somewhere else. That’s because we don’t want to duplicate the same code over and over again, right? That’s correct, duplication is bad, but tearing an object apart is even worse. Way worse. The same is true about ORM (JPA/Hibernate), where annotations are being actively used. Check this post, it explains what is wrong about ORM: ORM Is an Offensive Anti-Pattern. Annotations by themselves are not the key motivator, but they help us and encourage us by tearing objects apart and keeping parts in different places. They are containers, sessions, managers, controllers, etc.</p><h2 id="xmlelement">@XmlElement</h2><aside class="youtube"> <div class="box"> YouTube video #oV6Utb5Jows<div class="play"></div></div><div>Dependency Injection Container is a Bad Idea (webinar #9); 1 December 2015.</div></aside><p>This is how JAXB works, when you want to convert your POJO to XML. First, you attach the @XmlElement annotation to the getter:</p>
<pre>import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class Book { private final String title; public Book(final String title) { this.title = title; } @XmlElement public String getTitle() { return this.title; } }</pre>
<p>Then, you create a marshaller and ask it to convert an instance of class Book into XML:</p>
<pre>final Book book = new Book("0132350882", "Clean Code"); final JAXBContext ctx = JAXBContext.newInstance(Book.class); final Marshaller marshaller = ctx.createMarshaller(); marshaller.marshal(book, System.out);</pre>
<aside class="youtube"> <div class="box"> YouTube video #cv23Z6xpwDw<div class="play"></div></div><div>Java Annotations Are a Bad Idea; 20 June 2017.</div></aside><p>Who is creating the XML? Not the book. Someone else, outside of the class Book. This is very wrong. Instead, this is how this should have been done. First, the class that has no idea about XML:</p>
<pre>class DefaultBook implements Book { private final String title; DefaultBook(final String title) { this.title = title; } @Override public String getTitle() { return this.title; } }</pre>
<p>Then, the decorator that prints it to the XML:</p>
<pre>class XmlBook implements Book{ private final Book origin; XmlBook(final Book book) { this.origin = book; } @Override public String getTitle() { return this.origin.getTitle(); } public String toXML() { return String.format( "<book><title>%s</title></book>", this.getTitle() ); } }</pre>
<p>Now, in order to print the book in XML we do the following:</p>
<pre>String xml = new XmlBook( new DefaultBook("Elegant Objects") ).toXML();</pre>
<p>The XML printing functionality is inside XmlBook. If you don’t like the decorator idea, you can move the toXML() method to the DefaultBook class. It’s not important. What is important is that the functionality always stays where it belongs—inside the object. Only the object knows how to print itself to the XML. Nobody else!</p><h2 id="retryonfailure">@RetryOnFailure</h2><p>Here is an example (from my own library):</p>
<pre>import com.jcabi.aspects.RetryOnFailure; class Foo { @RetryOnFailure public String load(URL url) { return url.openConnection().getContent(); } }</pre>
<p>After compilation, we run a so called AOP weaver that technically turns our code into something like this:</p>
<pre>class Foo { public String load(URL url) { while (true) { try { return _Foo.load(url); } catch (Exception ex) { // ignore it } } } class _Foo { public String load(URL url) { return url.openConnection().getContent(); } } }</pre>
<p>I simplified the actual algorithm of retrying a method call on failure, but I’m sure you get the idea. AspectJ, the AOP engine, uses @RetryOnFailure annotation as a signal, informing us that the class has to be wrapped into another one. This is happening behind the scenes. We don’t see that supplementary class, which implements the retrying algorithm. But the bytecode produced by the AspectJ weaver contains a modified version of class Foo.</p><aside class="youtube"> <div class="box"> YouTube video #WSgP85kr6eU<div class="play"></div></div><div>Why Getters-and-Setters Is An Anti-Pattern? (webinar #4); 1 July 2015.</div></aside><p>That is exactly what is wrong with this approach—we don’t see and don’t control the instantiation of that supplementary object. Object composition, which is the most important process in object design, is hidden somewhere behind the scenes. You may say that we don’t need to see it since it’s supplementary. I disagree. We must see how our objects are composed. We may not care about how they work, but we must see the entire composition process.</p><p>A much better design would look like this (instead of annotations):</p>
<pre>Foo foo = new FooThatRetries(new Foo());</pre>
<p>And then, the implementation of FooThatRetries:</p>
<pre>class FooThatRetries implements Foo { private final Foo origin; FooThatRetries(Foo foo) { this.origin = foo; } public String load(URL url) { return new Retry().eval( new Retry.Algorithm<String>() { @Override public String eval() { return FooThatRetries.this.load(url); } } ); } }</pre>
<p>And now, the implementation of Retry:</p>
<pre>class Retry { public <T> T eval(Retry.Algorithm<T> algo) { while (true) { try { return algo.eval(); } catch (Exception ex) { // ignore it } } } interface Algorithm<T> { T eval(); } }</pre>
<p>Is the code longer? Yes. Is it cleaner? A lot more. I regret that I didn’t understand it two years ago, when I started to work with jcabi-aspects.</p><hr /><p>The bottom line is that annotations are bad. Don’t use them. What should be used instead? Object composition.</p><p>What could be worse than annotations? Configurations. For example, XML configurations. Spring XML configuration mechanisms is a perfect example of terrible design. I’ve said it many times before. Let me repeat it again—Spring Framework is one of the worst software products in the Java world. If you can stay away from it, you will do yourself a big favor.</p><p>There should not be any “configurations” in OOP. We can’t configure our objects if they are real objects. We can only instantiate them. And the best method of instantiation is operator new. This operator is the key instrument for an OOP developer. Taking it away from us and giving us “configuration mechanisms” is an unforgivable crime.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Annotations were introduced in Java 5, and we all got excited. Such a great instrument to make code shorter! No more Hibernate/Spring XML configuration files! Just annotations, right there in the code where we need them. No more marker interfaces, just a runtime-retained reflection-discoverable annotation! I was excited too. Moreover, I’ve made a few open source libraries which use annotations heavily. Take jcabi-aspects, for example. However, I’m not excited any more. Moreover, I believe that annotations are a big mistake in Java design.</p>
Gomorra (2008) by Matteo Garrone)<figcaption id="8ef9c86b">Gomorra (2008) by Matteo Garrone)</figcaption>
<aside class="youtube"> <div class="box"> YouTube video #g1ctRcW214w<div class="play"></div></div><div>Java Annotations Are a Big Mistake (webinar #14); 4 May 2016.</div></aside><p>Long story short, there is one big problem with annotations—they encourage us to implement object functionality outside of an object, which is against the very principle of encapsulation. The object is not solid any more, since its behavior is not defined entirely by its own methods—some of its functionality stays elsewhere. Why is it bad? Let’s see in a few examples.</p><h2 id="inject">@Inject</h2><p>Say we annotate a property with @Inject:</p>
<pre>import javax.inject.Inject; public class Books { @Inject private final DB db; // some methods here, which use this.db }</pre>
<p>Then we have an injector that knows what to inject:</p>
<pre>Injector injector = Guice.createInjector( new AbstractModule() { @Override public void configure() { this.bind(DB.class).toInstance( new Postgres("jdbc:postgresql:5740/main") ); } } );</pre>
<p>Now we’re making an instance of class Books via the container:</p>
<pre>Books books = injector.getInstance(Books.class);</pre>
<p>The class Books has no idea how and who will inject an instance of class DB into it. This will happen behind the scenes and outside of its control. The injection will do it. It may look convenient, but this attitude causes a lot of damage to the entire code base. The control is lost (not inverted, but lost!). The object is not in charge any more. It can’t be responsible for what’s happening to it.</p><p>Instead, here is how this should be done:</p>
<pre>class Books { private final DB db; Books(final DB base) { this.db = base; } // some methods here, which use this.db }</pre>
<p>This article explains why Dependency Injection containers are a wrong idea in the first place: Dependency Injection Containers are Code Polluters. Annotations basically provoke us to make the containers and use them. We move functionality outside of our objects and put it into containers, or somewhere else. That’s because we don’t want to duplicate the same code over and over again, right? That’s correct, duplication is bad, but tearing an object apart is even worse. Way worse. The same is true about ORM (JPA/Hibernate), where annotations are being actively used. Check this post, it explains what is wrong about ORM: ORM Is an Offensive Anti-Pattern. Annotations by themselves are not the key motivator, but they help us and encourage us by tearing objects apart and keeping parts in different places. They are containers, sessions, managers, controllers, etc.</p><h2 id="xmlelement">@XmlElement</h2><aside class="youtube"> <div class="box"> YouTube video #oV6Utb5Jows<div class="play"></div></div><div>Dependency Injection Container is a Bad Idea (webinar #9); 1 December 2015.</div></aside><p>This is how JAXB works, when you want to convert your POJO to XML. First, you attach the @XmlElement annotation to the getter:</p>
<pre>import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class Book { private final String title; public Book(final String title) { this.title = title; } @XmlElement public String getTitle() { return this.title; } }</pre>
<p>Then, you create a marshaller and ask it to convert an instance of class Book into XML:</p>
<pre>final Book book = new Book("0132350882", "Clean Code"); final JAXBContext ctx = JAXBContext.newInstance(Book.class); final Marshaller marshaller = ctx.createMarshaller(); marshaller.marshal(book, System.out);</pre>
<aside class="youtube"> <div class="box"> YouTube video #cv23Z6xpwDw<div class="play"></div></div><div>Java Annotations Are a Bad Idea; 20 June 2017.</div></aside><p>Who is creating the XML? Not the book. Someone else, outside of the class Book. This is very wrong. Instead, this is how this should have been done. First, the class that has no idea about XML:</p>
<pre>class DefaultBook implements Book { private final String title; DefaultBook(final String title) { this.title = title; } @Override public String getTitle() { return this.title; } }</pre>
<p>Then, the decorator that prints it to the XML:</p>
<pre>class XmlBook implements Book{ private final Book origin; XmlBook(final Book book) { this.origin = book; } @Override public String getTitle() { return this.origin.getTitle(); } public String toXML() { return String.format( "<book><title>%s</title></book>", this.getTitle() ); } }</pre>
<p>Now, in order to print the book in XML we do the following:</p>
<pre>String xml = new XmlBook( new DefaultBook("Elegant Objects") ).toXML();</pre>
<p>The XML printing functionality is inside XmlBook. If you don’t like the decorator idea, you can move the toXML() method to the DefaultBook class. It’s not important. What is important is that the functionality always stays where it belongs—inside the object. Only the object knows how to print itself to the XML. Nobody else!</p><h2 id="retryonfailure">@RetryOnFailure</h2><p>Here is an example (from my own library):</p>
<pre>import com.jcabi.aspects.RetryOnFailure; class Foo { @RetryOnFailure public String load(URL url) { return url.openConnection().getContent(); } }</pre>
<p>After compilation, we run a so called AOP weaver that technically turns our code into something like this:</p>
<pre>class Foo { public String load(URL url) { while (true) { try { return _Foo.load(url); } catch (Exception ex) { // ignore it } } } class _Foo { public String load(URL url) { return url.openConnection().getContent(); } } }</pre>
<p>I simplified the actual algorithm of retrying a method call on failure, but I’m sure you get the idea. AspectJ, the AOP engine, uses @RetryOnFailure annotation as a signal, informing us that the class has to be wrapped into another one. This is happening behind the scenes. We don’t see that supplementary class, which implements the retrying algorithm. But the bytecode produced by the AspectJ weaver contains a modified version of class Foo.</p><aside class="youtube"> <div class="box"> YouTube video #WSgP85kr6eU<div class="play"></div></div><div>Why Getters-and-Setters Is An Anti-Pattern? (webinar #4); 1 July 2015.</div></aside><p>That is exactly what is wrong with this approach—we don’t see and don’t control the instantiation of that supplementary object. Object composition, which is the most important process in object design, is hidden somewhere behind the scenes. You may say that we don’t need to see it since it’s supplementary. I disagree. We must see how our objects are composed. We may not care about how they work, but we must see the entire composition process.</p><p>A much better design would look like this (instead of annotations):</p>
<pre>Foo foo = new FooThatRetries(new Foo());</pre>
<p>And then, the implementation of FooThatRetries:</p>
<pre>class FooThatRetries implements Foo { private final Foo origin; FooThatRetries(Foo foo) { this.origin = foo; } public String load(URL url) { return new Retry().eval( new Retry.Algorithm<String>() { @Override public String eval() { return FooThatRetries.this.load(url); } } ); } }</pre>
<p>And now, the implementation of Retry:</p>
<pre>class Retry { public <T> T eval(Retry.Algorithm<T> algo) { while (true) { try { return algo.eval(); } catch (Exception ex) { // ignore it } } } interface Algorithm<T> { T eval(); } }</pre>
<p>Is the code longer? Yes. Is it cleaner? A lot more. I regret that I didn’t understand it two years ago, when I started to work with jcabi-aspects.</p><hr /><p>The bottom line is that annotations are bad. Don’t use them. What should be used instead? Object composition.</p><p>What could be worse than annotations? Configurations. For example, XML configurations. Spring XML configuration mechanisms is a perfect example of terrible design. I’ve said it many times before. Let me repeat it again—Spring Framework is one of the worst software products in the Java world. If you can stay away from it, you will do yourself a big favor.</p><p>There should not be any “configurations” in OOP. We can’t configure our objects if they are real objects. We can only instantiate them. And the best method of instantiation is operator new. This operator is the key instrument for an OOP developer. Taking it away from us and giving us “configuration mechanisms” is an unforgivable crime.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Printers Instead of Getters </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/04/05/printers-instead-of-getters.html>12 Best</li> <li /2016/04/05/printers-instead-of-getters.html>All 292</li> <li /2016/04/05/printers-instead-of-getters.html>Webinars</li> <li /2016/04/05/printers-instead-of-getters.html>Talks</li> <li /2016/04/05/printers-instead-of-getters.html>Books</li> <li /2016/04/05/printers-instead-of-getters.html>Papers</li> <li /2016/04/05/printers-instead-of-getters.html>Pets</li> <li /2016/04/05/printers-instead-of-getters.html class=”highlighted”>Trainings</li> <li /2016/04/05/printers-instead-of-getters.html>Award</li> <li /2016/04/05/printers-instead-of-getters.html>Testimonials</li> <li /2016/04/05/printers-instead-of-getters.html>Shift-M</li> <li /2016/04/05/printers-instead-of-getters.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Printers Instead of Getters</h1><aside class='book'>book coverRead more about this subject in Section 5.3
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Getters and setters are evil. No need to argue about this, it’s settled. You disagree? Let’s discuss that later. For now, let’s say, we want to get rid of getters. The key question is how is it possible at all? We do need to get the data out of an object, right? Nope. Wrong.</p>
Le fabuleux destin d'Amélie Poulain (2001) by Jean-Pierre Jeunet<figcaption id="a123a2ca">Le fabuleux destin d'Amélie Poulain (2001) by Jean-Pierre Jeunet</figcaption>
<p>I’m suggesting to use “printers” instead. Instead of exposing data via getters, an object will have a functionality of printing itself to some media.</p><p>Let’s say this is our class:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; }</pre>
<p>We need it to be transferred into XML format. A more or less traditional way to do it is via getters and JAXB:</p>
<pre>import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; @XmlElement public String getIsbn() { return this.isbn; } @XmlElement public String getTitle() { return this.title; } }</pre>
<p>This is a very offensive way of treating the object. We’re basically exposing everything that’s inside to the public. It was a nice little self-sufficient solid object and we turned it into a bag of data, which anyone can access in many possible ways. We can access it for reading, of course.</p><p>It is convenient to have these getters, you may say. We are all used to them. If we want to convert it into JSON, they will be very helpful. If we want to use this poor object as a data object in JSP, getters will help us. There are many examples in Java, where getters are being actively used.</p><aside class="youtube"> <div class="box"> YouTube video #_Q0cNykXB04<div class="play"></div></div><div>Printers Instead of Getters in OOP (webinar #18); 7 September 2016.</div></aside><p>This is not because they are so effective. This is because we’re so procedural in our way of thinking. We don’t trust our objects. We only trust the data they store. We don’t want this Book object to generate the XML. We want it to give us the data. We will build the XML. The Book is too stupid to do that job. We’re way smarter!</p><p>I’m suggesting to stop thinking this way. Instead, let’s try to give this poor Book a chance, and equip it with a “printer”:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; public String toXML() { return String.format( "<book><isbn>%s</isbn><title>%s</title></book>", this.isbn, this.title ); } }</pre>
<p>This isn’t the best implementation, but you got the idea. The object is not exposing its internals any more. We can’t get its ISBN and its title. We can only ask it to print itself in XML format.</p><p>We can add an additional printer, if another format is required:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; public String toJSON() { return String.format( "{\"isbn\":\"%s\", \"title\":\"%s\"}", this.isbn, this.title ); } }</pre>
<p>Again, not the best implementation, but you see what I’m trying to show. Each time we need a new format, we create a new printer.</p><p>You may say that the object will be rather big if there will be many formats. That’s true, but a big object is a bad design in the first place. I would say that if there is more than one printer—it’s a problem.</p><p>So, what to do if we need multiple formats? Use “media,” where that printers will be able to print to. Say, we have an object that represents a record in MySQL. We want it to be printable to XML, HTML, JSON, some binary format and God knows what else. We can add that many printers to it, but the object will be big and ugly. To avoid that, introduce a new object, that represents the media where the data will be printed to:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; public Media print(Media media) { return media .with("isbn", this.isbn) .with("title", this.title); } }</pre>
<p>Again, it’s a very primitive design of that immutable Media class, but you got the idea—the media accepts the data. Now, we want to print our object to JSON (this design is not really perfect, since JsonObjectBuilder is not immutable, even though it looks like one…):</p>
<pre>class JsonMedia implements Media { private final JsonObjectBuilder builder; JsonMedia() { this("book"); } JsonMedia(String head) { this(Json.createObjectBuilder().add(head)); } JsonMedia(JsonObjectBuilder bdr) { this.builder = bdr; } @Override public Media with(String name, String value) { return new JsonMedia( this.builder.add(name, value) ); } public JsonObject json() { return this.builder.build(); } }</pre>
<p>Now, we make an instance of JsonMedia and ask our book to print itself there:</p>
<pre>JsonMedia media = new JsonMedia("book"); book.print(media); JsonObject json = media.json();</pre>
<p>Voilà! The JSON object is ready and the book has no idea about what exactly what printed just now. We need to print the book to XML? We create XmlMedia, which will print the book to XML. The Book class stays small, while the complexity of “media” objects is unlimited.</p><p>My point here is simple—no getters, just printers!</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Getters and setters are evil. No need to argue about this, it’s settled. You disagree? Let’s discuss that later. For now, let’s say, we want to get rid of getters. The key question is how is it possible at all? We do need to get the data out of an object, right? Nope. Wrong.</p>
Le fabuleux destin d'Amélie Poulain (2001) by Jean-Pierre Jeunet<figcaption id="a123a2ca">Le fabuleux destin d'Amélie Poulain (2001) by Jean-Pierre Jeunet</figcaption>
<p>I’m suggesting to use “printers” instead. Instead of exposing data via getters, an object will have a functionality of printing itself to some media.</p><p>Let’s say this is our class:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; }</pre>
<p>We need it to be transferred into XML format. A more or less traditional way to do it is via getters and JAXB:</p>
<pre>import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; @XmlElement public String getIsbn() { return this.isbn; } @XmlElement public String getTitle() { return this.title; } }</pre>
<p>This is a very offensive way of treating the object. We’re basically exposing everything that’s inside to the public. It was a nice little self-sufficient solid object and we turned it into a bag of data, which anyone can access in many possible ways. We can access it for reading, of course.</p><p>It is convenient to have these getters, you may say. We are all used to them. If we want to convert it into JSON, they will be very helpful. If we want to use this poor object as a data object in JSP, getters will help us. There are many examples in Java, where getters are being actively used.</p><aside class="youtube"> <div class="box"> YouTube video #_Q0cNykXB04<div class="play"></div></div><div>Printers Instead of Getters in OOP (webinar #18); 7 September 2016.</div></aside><p>This is not because they are so effective. This is because we’re so procedural in our way of thinking. We don’t trust our objects. We only trust the data they store. We don’t want this Book object to generate the XML. We want it to give us the data. We will build the XML. The Book is too stupid to do that job. We’re way smarter!</p><p>I’m suggesting to stop thinking this way. Instead, let’s try to give this poor Book a chance, and equip it with a “printer”:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; public String toXML() { return String.format( "<book><isbn>%s</isbn><title>%s</title></book>", this.isbn, this.title ); } }</pre>
<p>This isn’t the best implementation, but you got the idea. The object is not exposing its internals any more. We can’t get its ISBN and its title. We can only ask it to print itself in XML format.</p><p>We can add an additional printer, if another format is required:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; public String toJSON() { return String.format( "{\"isbn\":\"%s\", \"title\":\"%s\"}", this.isbn, this.title ); } }</pre>
<p>Again, not the best implementation, but you see what I’m trying to show. Each time we need a new format, we create a new printer.</p><p>You may say that the object will be rather big if there will be many formats. That’s true, but a big object is a bad design in the first place. I would say that if there is more than one printer—it’s a problem.</p><p>So, what to do if we need multiple formats? Use “media,” where that printers will be able to print to. Say, we have an object that represents a record in MySQL. We want it to be printable to XML, HTML, JSON, some binary format and God knows what else. We can add that many printers to it, but the object will be big and ugly. To avoid that, introduce a new object, that represents the media where the data will be printed to:</p>
<pre>public class Book { private final String isbn = "0735619654"; private final String title = "Object Thinking"; public Media print(Media media) { return media .with("isbn", this.isbn) .with("title", this.title); } }</pre>
<p>Again, it’s a very primitive design of that immutable Media class, but you got the idea—the media accepts the data. Now, we want to print our object to JSON (this design is not really perfect, since JsonObjectBuilder is not immutable, even though it looks like one…):</p>
<pre>class JsonMedia implements Media { private final JsonObjectBuilder builder; JsonMedia() { this("book"); } JsonMedia(String head) { this(Json.createObjectBuilder().add(head)); } JsonMedia(JsonObjectBuilder bdr) { this.builder = bdr; } @Override public Media with(String name, String value) { return new JsonMedia( this.builder.add(name, value) ); } public JsonObject json() { return this.builder.build(); } }</pre>
<p>Now, we make an instance of JsonMedia and ask our book to print itself there:</p>
<pre>JsonMedia media = new JsonMedia("book"); book.print(media); JsonObject json = media.json();</pre>
<p>Voilà! The JSON object is ready and the book has no idea about what exactly what printed just now. We need to print the book to XML? We create XmlMedia, which will print the book to XML. The Book class stays small, while the complexity of “media” objects is unlimited.</p><p>My point here is simple—no getters, just printers!</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Try. Finally. If. Not. Null. </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/03/22/try-finally-if-not-null.html>12 Best</li> <li /2016/03/22/try-finally-if-not-null.html>All 292</li> <li /2016/03/22/try-finally-if-not-null.html>Webinars</li> <li /2016/03/22/try-finally-if-not-null.html>Talks</li> <li /2016/03/22/try-finally-if-not-null.html>Books</li> <li /2016/03/22/try-finally-if-not-null.html>Papers</li> <li /2016/03/22/try-finally-if-not-null.html>Pets</li> <li /2016/03/22/try-finally-if-not-null.html class=”highlighted”>Trainings</li> <li /2016/03/22/try-finally-if-not-null.html>Award</li> <li /2016/03/22/try-finally-if-not-null.html>Testimonials</li> <li /2016/03/22/try-finally-if-not-null.html>Shift-M</li> <li /2016/03/22/try-finally-if-not-null.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Try. Finally. If. Not. Null.</h1><aside class='book'>book coverRead more about this subject in Section 2.6
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>There is a very typical mistake in pre-Java7 “try/finally” scenario, which I keep seeing in so many code reviews. I just have to write about it. Java7 introduced a solution, but it doesn’t cover all situations. Sometimes we need to deal with non-AutoCloseable resources. Let’s open and close them correctly, please.</p>
Lock, Stock and Two Smoking Barrels (1998) by Guy Ritchie<figcaption id="118d4d8e">Lock, Stock and Two Smoking Barrels (1998) by Guy Ritchie</figcaption>
<p>This is how it looks (assuming we are in Java 6):</p>
<pre>InputStream input = null; try { input = url.openStream(); // reads the stream, throws IOException } catch (IOException ex) { throw new RuntimeException(ex); } finally { if (input != null) { input.close(); } }</pre>
<aside class="youtube"> <div class="box"> YouTube video #o3aNJX7AP3M<div class="play"></div></div><div>What is Wrong About NULL in OOP? (webinar #3); 3 June 2015.</div></aside><p>I already wrote about null and its evil nature. Here it comes again. If you just follow the rule of “not using NULL anywhere ever,” this code would need an immediate refactoring. Its correct version will look like this:</p>
<pre>final InputStream input = url.openStream(); try { // reads the stream, throws IOException } catch (IOException ex) { throw new RuntimeException(ex); } finally { input.close(); }</pre>
<p>There is no null anymore and it’s very clean. Isn’t it?</p><p>There are situations when opening the resource itself throws IOException and we can’t put it outside of try/catch. In that case, we have to have two try/catch blocks:</p>
<pre>final InputStream input; try { input = url.openStream(); } catch (IOException ex) { throw new RuntimeException(ex); } try { // reads the stream, throws IOException } catch (IOException ex) { throw new RuntimeException(ex); } finally { input.close(); }</pre>
<p>But there should be no null, never!</p><p>The presence of null in Java code is a clear indicator of code smell. Something is not right if you have to use null. The only place where the presence of null is justified is where we’re using third-party APIs or JDK. They may return null sometimes because… well, their design is bad. We have no other option but to do if(x==null). But that’s it. No other places are good for null.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>There is a very typical mistake in pre-Java7 “try/finally” scenario, which I keep seeing in so many code reviews. I just have to write about it. Java7 introduced a solution, but it doesn’t cover all situations. Sometimes we need to deal with non-AutoCloseable resources. Let’s open and close them correctly, please.</p>
Lock, Stock and Two Smoking Barrels (1998) by Guy Ritchie<figcaption id="118d4d8e">Lock, Stock and Two Smoking Barrels (1998) by Guy Ritchie</figcaption>
<p>This is how it looks (assuming we are in Java 6):</p>
<pre>InputStream input = null; try { input = url.openStream(); // reads the stream, throws IOException } catch (IOException ex) { throw new RuntimeException(ex); } finally { if (input != null) { input.close(); } }</pre>
<aside class="youtube"> <div class="box"> YouTube video #o3aNJX7AP3M<div class="play"></div></div><div>What is Wrong About NULL in OOP? (webinar #3); 3 June 2015.</div></aside><p>I already wrote about null and its evil nature. Here it comes again. If you just follow the rule of “not using NULL anywhere ever,” this code would need an immediate refactoring. Its correct version will look like this:</p>
<pre>final InputStream input = url.openStream(); try { // reads the stream, throws IOException } catch (IOException ex) { throw new RuntimeException(ex); } finally { input.close(); }</pre>
<p>There is no null anymore and it’s very clean. Isn’t it?</p><p>There are situations when opening the resource itself throws IOException and we can’t put it outside of try/catch. In that case, we have to have two try/catch blocks:</p>
<pre>final InputStream input; try { input = url.openStream(); } catch (IOException ex) { throw new RuntimeException(ex); } try { // reads the stream, throws IOException } catch (IOException ex) { throw new RuntimeException(ex); } finally { input.close(); }</pre>
<p>But there should be no null, never!</p><p>The presence of null in Java code is a clear indicator of code smell. Something is not right if you have to use null. The only place where the presence of null is justified is where we’re using third-party APIs or JDK. They may return null sometimes because… well, their design is bad. We have no other option but to do if(x==null). But that’s it. No other places are good for null.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Are You Still Debugging? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/02/09/are-you-still-debugging.html>12 Best</li> <li /2016/02/09/are-you-still-debugging.html>All 292</li> <li /2016/02/09/are-you-still-debugging.html>Webinars</li> <li /2016/02/09/are-you-still-debugging.html>Talks</li> <li /2016/02/09/are-you-still-debugging.html>Books</li> <li /2016/02/09/are-you-still-debugging.html>Papers</li> <li /2016/02/09/are-you-still-debugging.html>Pets</li> <li /2016/02/09/are-you-still-debugging.html class=”highlighted”>Trainings</li> <li /2016/02/09/are-you-still-debugging.html>Award</li> <li /2016/02/09/are-you-still-debugging.html>Testimonials</li> <li /2016/02/09/are-you-still-debugging.html>Shift-M</li> <li /2016/02/09/are-you-still-debugging.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Are You Still Debugging?</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Russian</li> <li>add yours!</li></ul><p class="unprintable"><p>Debugging is “a process of running a program/method interactively, breaking execution flow after each statement and showing…” In a nutshell, it is a very useful technique … for a bad programmer. Or an old programmer who is still writing procedural code in C. Object-oriented programmers never debug their code—they write unit tests. My point here is that unit testing is a technique that completely replaces debugging. If debugging is required, the design is bad.</p>
The Revenant (2015) by Alejandro G. Iñárritu<figcaption id="867738b9">The Revenant (2015) by Alejandro G. Iñárritu</figcaption>
<p>Let’s say I’m a bad imperative procedural programmer, and this is my Java code:</p>
<pre>class FileUtils { public static Iterable<String> readWords(File f) { String text = new String( Files.readAllBytes(Paths.get(f)), "UTF-8" ); Set<String> words = new HashSet<>(); for (String word : text.split(" ")) { words.add(word); } return words; } }</pre>
<p>This static utility method reads file content and then finds all the unique words in it. Pretty simple. However, if it doesn’t work, what do we do? Let’s say this is the file:</p>
<pre>We know what we are, but know not what we may be.</pre>
<p>From it, we get this list of words:</p>
<pre>"We" "know" "what" "we" "are,\n" "but" "not" "may" "be\n"</pre>
<p>Now that doesn’t look right to me … so what is the next step? Either the file reading doesn’t work correctly or the split is broken. Let’s debug, right? Let’s give it a file through an input and go step by step, tracing and watching the variables. We’ll find the bug and fix it. But when a similar problem shows up, we’ll have to debug again! And that’s what unit testing is supposed to prevent.</p><p>We’re supposed to create a unit test once, in which the problem is reproduced. Then we fix the problem and make sure the test passes. That’s how we save our investments in problem solving. We won’t fix it again, because it won’t happen again. Our test will prevent it from happening.</p><aside class="quote">If you perceive debugging to be faster and easier, think about the quality of your code</aside><p>However, all this will work only if it’s easy to create a unit test. If it’s difficult, I’ll be too lazy to do it. I will just debug and fix the problem. In this particular example, creating a test is a rather expensive procedure. What I mean is the complexity of the unit test will be rather high. We have to create a temporary file, fill it with data, run the method, and check the results. To find out what’s going on and where the bug is, I’ll have to create a number of tests. To avoid code duplication, I’ll also have to create some supplementary utilities to help me create that temporary file and fill it with data. That’s a lot of work. Well, maybe not “a lot,” but way more than a few minutes of debugging.</p><aside class="youtube"> <div class="box"> YouTube video #Mj1gA5mEk68<div class="play"></div></div><div>Unit Testing vs Debugging (webinar #26); 12 July 2017.</div></aside><p>Thus, if you perceive debugging to be faster and easier, think about the quality of your code. I bet it has a lot of opportunities for refactoring, just like the code from the example above. Here is how I would modify it. First of all, I would turn it into a class, because utility static methods are a bad practice:</p>
<pre>class Words implements Iterable<String> { private final File file; Words(File src) { this.file = src; } @Override public Iterator<String> iterator() { String text = new String( Files.readAllBytes(Paths.get(this.file)), "UTF-8" ); Set<String> words = new HashSet<>(); for (String word : text.split(" ")) { words.add(word); } return words.iterator(); } }</pre>
<p>It looks better already, but the complexity is still there. Next, I would break it down into smaller classes:</p>
<pre>class Text { private final File file; Text(File src) { this.file = src; } @Override public String toString() { return new String( Files.readAllBytes(Paths.get(this.file)), "UTF-8" ); } } class Words implements Iterable<String> { private final String text; Words(String txt) { this.text = txt; } @Override public Iterator<String> iterator() { Set<String> words = new HashSet<>(); for (String word : this.text.split(" ")) { words.add(word); } return words.iterator(); } }</pre>
<p>What do you think now? Writing a test for the Words class is a pretty trivial task:</p>
<pre>import org.junit.Test; import static org.hamcrest.MatcherAssert.*; import static org.hamcrest.Matchers.*; public class WordsTest { @Test public void parsesSimpleText() { assertThat( new Words("How are you?"), hasItems("How", "are", "you") ); } }</pre>
<p>How much time did that take? Less than a minute. We don’t need to create a temporary file and load it with data, because class Words doesn’t do anything with files. It just parses the incoming string and finds the unique words in it. Now it’s easy to fix, since the test is small and we can easily create more tests; for example:</p>
<pre>import org.junit.Test; import static org.hamcrest.MatcherAssert.*; import static org.hamcrest.Matchers.*; public class WordsTest { @Test public void parsesSimpleText() { assertThat( new Words("How are you?"), hasItems("How", "are", "you") ); } @Test public void parsesMultipleLines() { assertThat( new Words("first line\nsecond line\n"), hasItems("first", "second", "line") ); } }</pre>
<p>My point is that debugging is necessary when the amount of time to write a unit test is significantly more than the time it takes to click those Trace-In/Trace-Out buttons. And it’s logical. We all are lazy and want fast and easy solutions. But debugging burns time and wastes energy. It helps us find problems but doesn’t help prevent them from reappearing.</p><p>Debugging is needed when our code is procedural and algorithmic—when the code is all about how the goal should be achieved instead of what the goal is. See the examples above again. The first static method is all about how we read the file, parse it, and find words. It’s even named readWords() (a verb). To the contrary, the second example is about what will be achieved. It’s either the Text of the file or Words of the text (both are nouns).</p><p>I believe there is no place for debugging in clean object-oriented programming. Only unit testing!</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Debugging is “a process of running a program/method interactively, breaking execution flow after each statement and showing…” In a nutshell, it is a very useful technique … for a bad programmer. Or an old programmer who is still writing procedural code in C. Object-oriented programmers never debug their code—they write unit tests. My point here is that unit testing is a technique that completely replaces debugging. If debugging is required, the design is bad.</p>
The Revenant (2015) by Alejandro G. Iñárritu<figcaption id="867738b9">The Revenant (2015) by Alejandro G. Iñárritu</figcaption>
<p>Let’s say I’m a bad imperative procedural programmer, and this is my Java code:</p>
<pre>class FileUtils { public static Iterable<String> readWords(File f) { String text = new String( Files.readAllBytes(Paths.get(f)), "UTF-8" ); Set<String> words = new HashSet<>(); for (String word : text.split(" ")) { words.add(word); } return words; } }</pre>
<p>This static utility method reads file content and then finds all the unique words in it. Pretty simple. However, if it doesn’t work, what do we do? Let’s say this is the file:</p>
<pre>We know what we are, but know not what we may be.</pre>
<p>From it, we get this list of words:</p>
<pre>"We" "know" "what" "we" "are,\n" "but" "not" "may" "be\n"</pre>
<p>Now that doesn’t look right to me … so what is the next step? Either the file reading doesn’t work correctly or the split is broken. Let’s debug, right? Let’s give it a file through an input and go step by step, tracing and watching the variables. We’ll find the bug and fix it. But when a similar problem shows up, we’ll have to debug again! And that’s what unit testing is supposed to prevent.</p><p>We’re supposed to create a unit test once, in which the problem is reproduced. Then we fix the problem and make sure the test passes. That’s how we save our investments in problem solving. We won’t fix it again, because it won’t happen again. Our test will prevent it from happening.</p><aside class="quote">If you perceive debugging to be faster and easier, think about the quality of your code</aside><p>However, all this will work only if it’s easy to create a unit test. If it’s difficult, I’ll be too lazy to do it. I will just debug and fix the problem. In this particular example, creating a test is a rather expensive procedure. What I mean is the complexity of the unit test will be rather high. We have to create a temporary file, fill it with data, run the method, and check the results. To find out what’s going on and where the bug is, I’ll have to create a number of tests. To avoid code duplication, I’ll also have to create some supplementary utilities to help me create that temporary file and fill it with data. That’s a lot of work. Well, maybe not “a lot,” but way more than a few minutes of debugging.</p><aside class="youtube"> <div class="box"> YouTube video #Mj1gA5mEk68<div class="play"></div></div><div>Unit Testing vs Debugging (webinar #26); 12 July 2017.</div></aside><p>Thus, if you perceive debugging to be faster and easier, think about the quality of your code. I bet it has a lot of opportunities for refactoring, just like the code from the example above. Here is how I would modify it. First of all, I would turn it into a class, because utility static methods are a bad practice:</p>
<pre>class Words implements Iterable<String> { private final File file; Words(File src) { this.file = src; } @Override public Iterator<String> iterator() { String text = new String( Files.readAllBytes(Paths.get(this.file)), "UTF-8" ); Set<String> words = new HashSet<>(); for (String word : text.split(" ")) { words.add(word); } return words.iterator(); } }</pre>
<p>It looks better already, but the complexity is still there. Next, I would break it down into smaller classes:</p>
<pre>class Text { private final File file; Text(File src) { this.file = src; } @Override public String toString() { return new String( Files.readAllBytes(Paths.get(this.file)), "UTF-8" ); } } class Words implements Iterable<String> { private final String text; Words(String txt) { this.text = txt; } @Override public Iterator<String> iterator() { Set<String> words = new HashSet<>(); for (String word : this.text.split(" ")) { words.add(word); } return words.iterator(); } }</pre>
<p>What do you think now? Writing a test for the Words class is a pretty trivial task:</p>
<pre>import org.junit.Test; import static org.hamcrest.MatcherAssert.*; import static org.hamcrest.Matchers.*; public class WordsTest { @Test public void parsesSimpleText() { assertThat( new Words("How are you?"), hasItems("How", "are", "you") ); } }</pre>
<p>How much time did that take? Less than a minute. We don’t need to create a temporary file and load it with data, because class Words doesn’t do anything with files. It just parses the incoming string and finds the unique words in it. Now it’s easy to fix, since the test is small and we can easily create more tests; for example:</p>
<pre>import org.junit.Test; import static org.hamcrest.MatcherAssert.*; import static org.hamcrest.Matchers.*; public class WordsTest { @Test public void parsesSimpleText() { assertThat( new Words("How are you?"), hasItems("How", "are", "you") ); } @Test public void parsesMultipleLines() { assertThat( new Words("first line\nsecond line\n"), hasItems("first", "second", "line") ); } }</pre>
<p>My point is that debugging is necessary when the amount of time to write a unit test is significantly more than the time it takes to click those Trace-In/Trace-Out buttons. And it’s logical. We all are lazy and want fast and easy solutions. But debugging burns time and wastes energy. It helps us find problems but doesn’t help prevent them from reappearing.</p><p>Debugging is needed when our code is procedural and algorithmic—when the code is all about how the goal should be achieved instead of what the goal is. See the examples above again. The first static method is all about how we read the file, parse it, and find words. It’s even named readWords() (a verb). To the contrary, the second example is about what will be achieved. It’s either the Text of the file or Words of the text (both are nouns).</p><p>I believe there is no place for debugging in clean object-oriented programming. Only unit testing!</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Design Patterns and Anti-Patterns, Love and Hate </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>12 Best</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>All 292</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Webinars</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Talks</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Books</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Papers</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Pets</li> <li /2016/02/03/design-patterns-and-anti-patterns.html class=”highlighted”>Trainings</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Award</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Testimonials</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Shift-M</li> <li /2016/02/03/design-patterns-and-anti-patterns.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Design Patterns and Anti-Patterns, Love and Hate</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Design Patterns are … Come on, you know what they are. They are something we love and hate. We love them because they let us write code without thinking. We hate them when we see the code of someone who is used to writing code without thinking. Am I wrong? Now, let me try to go through all of them and show you how much I love or hate each one. Follow me, in alphabetic order.</p>
The Shining (1980) by Stanley Kubrick<figcaption id="27f582ec">The Shining (1980) by Stanley Kubrick</figcaption>
<aside class="youtube"> <div class="box"> YouTube video #WSgP85kr6eU<div class="play"></div></div><div>Why Getters-and-Setters Is An Anti-Pattern? (webinar #4); 1 July 2015.</div></aside><p>Abstract Factory. It’s OK.</p><p>Adapter. Good one!</p><p>Bridge. Good one!</p><p>Builder. Terrible concept, since it encourages us to create and use big, complex objects. If you need a builder, there is already something wrong in your code. Refactor it so any object is easy to create through its constructors.</p><p>Chain of Responsibility. Seems fine.</p><p>Command. It’s OK.</p><p>Composite. Good one; check out this too.</p><p>Data Transfer Object. It’s just a shame.</p><p>Decorator. My favorite one. I highly recommend you use it.</p><p>Facade. Bad idea. In OOP, we need objects and only objects, not facades for them. This design pattern is very procedural in its spirit, since a facade is nothing more than a collection of procedures.</p><p>Factory Method. This one seems OK.</p><p>Flyweight. It’s a workaround, as I see it, so it’s not a good design pattern. I would recommend you not use it unless there is a really critical performance issue. But calling it a design pattern … no way. A fix for a performance problem in Java? Yes.</p><p>Front Controller. Terrible idea, as well as the entire MVC. It’s very procedural, that’s why.</p><p>Interpreter. It’s OK, but I don’t like the name. “Expression” would be a much better alternative.</p><p>Iterator. Bad idea, since it is mutable. It would be much better to have immutable “cursors.”</p><p>Lazy Initialization. It’s OK.</p><p>Marker. It’s a terrible idea, along with reflection and type casting.</p><p>MVC. Bad idea, since it’s very procedural. Controllers are the key broken element in this concept. We need real objects, not procedural controllers.</p><p>Mediator. I don’t like it. Even though it sounds like a technique for decreasing complexity and coupling, it is not really object-oriented. Who is this mediator? Just a “channel” between objects? Why shouldn’t objects communicate directly? Because they are too complex? Make them smaller and simpler, rather than inventing these mediators.</p><p>Memento. This idea implies that objects are mutable, which I’m against in general.</p><p>Module. If Wikipedia is right about this pattern, it’s something even more terrible than the Singleton.</p><p>Multiton. Really bad idea. Same as Singleton.</p><p>Null Object. Good one. By the way, see Why NULL Is Bad</p><p>Object Pool. Good one.</p><p>Observer. The idea is good, but the name is bad, since it ends with -ER. A much better one would be “Source” and “Target.” The Source generates events and the Target listens to them.</p><p>ORM. It’s terrible and “offensive”; check this out.</p><p>Prototype. Good idea, but what does it have to do with OOP?</p><p>Proxy. Good one.</p><p>RAII. This is a really good one, and I highly recommend you use it.</p><p>Servant. A very bad idea, because it’s highly procedural.</p><p>Singleton. It’s the king of all anti-patterns. Stay away from it at all costs.</p><p>Specification. It’s OK.</p><p>State. Although it’s not implied, I feel that in most cases the use of this pattern results in mutability, a code characteristic that I’m generally against.</p><p>Strategy. A good one.</p><p>Template Method. is wrong, since implementation inheritance is procedural.</p><p>Visitor. A rather procedural concept that treats objects as data structures, which we can manipulate.</p><hr /><p>I have nothing against concurrency patterns either; they are all good, since they have almost nothing to do with object-oriented programming.</p><p>If you know some other design (anti-)patterns, let me know in the comments below. I’ll add them here.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Design Patterns are … Come on, you know what they are. They are something we love and hate. We love them because they let us write code without thinking. We hate them when we see the code of someone who is used to writing code without thinking. Am I wrong? Now, let me try to go through all of them and show you how much I love or hate each one. Follow me, in alphabetic order.</p>
The Shining (1980) by Stanley Kubrick<figcaption id="27f582ec">The Shining (1980) by Stanley Kubrick</figcaption>
<aside class="youtube"> <div class="box"> YouTube video #WSgP85kr6eU<div class="play"></div></div><div>Why Getters-and-Setters Is An Anti-Pattern? (webinar #4); 1 July 2015.</div></aside><p>Abstract Factory. It’s OK.</p><p>Adapter. Good one!</p><p>Bridge. Good one!</p><p>Builder. Terrible concept, since it encourages us to create and use big, complex objects. If you need a builder, there is already something wrong in your code. Refactor it so any object is easy to create through its constructors.</p><p>Chain of Responsibility. Seems fine.</p><p>Command. It’s OK.</p><p>Composite. Good one; check out this too.</p><p>Data Transfer Object. It’s just a shame.</p><p>Decorator. My favorite one. I highly recommend you use it.</p><p>Facade. Bad idea. In OOP, we need objects and only objects, not facades for them. This design pattern is very procedural in its spirit, since a facade is nothing more than a collection of procedures.</p><p>Factory Method. This one seems OK.</p><p>Flyweight. It’s a workaround, as I see it, so it’s not a good design pattern. I would recommend you not use it unless there is a really critical performance issue. But calling it a design pattern … no way. A fix for a performance problem in Java? Yes.</p><p>Front Controller. Terrible idea, as well as the entire MVC. It’s very procedural, that’s why.</p><p>Interpreter. It’s OK, but I don’t like the name. “Expression” would be a much better alternative.</p><p>Iterator. Bad idea, since it is mutable. It would be much better to have immutable “cursors.”</p><p>Lazy Initialization. It’s OK.</p><p>Marker. It’s a terrible idea, along with reflection and type casting.</p><p>MVC. Bad idea, since it’s very procedural. Controllers are the key broken element in this concept. We need real objects, not procedural controllers.</p><p>Mediator. I don’t like it. Even though it sounds like a technique for decreasing complexity and coupling, it is not really object-oriented. Who is this mediator? Just a “channel” between objects? Why shouldn’t objects communicate directly? Because they are too complex? Make them smaller and simpler, rather than inventing these mediators.</p><p>Memento. This idea implies that objects are mutable, which I’m against in general.</p><p>Module. If Wikipedia is right about this pattern, it’s something even more terrible than the Singleton.</p><p>Multiton. Really bad idea. Same as Singleton.</p><p>Null Object. Good one. By the way, see Why NULL Is Bad</p><p>Object Pool. Good one.</p><p>Observer. The idea is good, but the name is bad, since it ends with -ER. A much better one would be “Source” and “Target.” The Source generates events and the Target listens to them.</p><p>ORM. It’s terrible and “offensive”; check this out.</p><p>Prototype. Good idea, but what does it have to do with OOP?</p><p>Proxy. Good one.</p><p>RAII. This is a really good one, and I highly recommend you use it.</p><p>Servant. A very bad idea, because it’s highly procedural.</p><p>Singleton. It’s the king of all anti-patterns. Stay away from it at all costs.</p><p>Specification. It’s OK.</p><p>State. Although it’s not implied, I feel that in most cases the use of this pattern results in mutability, a code characteristic that I’m generally against.</p><p>Strategy. A good one.</p><p>Template Method. is wrong, since implementation inheritance is procedural.</p><p>Visitor. A rather procedural concept that treats objects as data structures, which we can manipulate.</p><hr /><p>I have nothing against concurrency patterns either; they are all good, since they have almost nothing to do with object-oriented programming.</p><p>If you know some other design (anti-)patterns, let me know in the comments below. I’ll add them here.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Defensive Programming via Validating Decorators </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/01/26/defensive-programming.html>12 Best</li> <li /2016/01/26/defensive-programming.html>All 292</li> <li /2016/01/26/defensive-programming.html>Webinars</li> <li /2016/01/26/defensive-programming.html>Talks</li> <li /2016/01/26/defensive-programming.html>Books</li> <li /2016/01/26/defensive-programming.html>Papers</li> <li /2016/01/26/defensive-programming.html>Pets</li> <li /2016/01/26/defensive-programming.html class=”highlighted”>Trainings</li> <li /2016/01/26/defensive-programming.html>Award</li> <li /2016/01/26/defensive-programming.html>Testimonials</li> <li /2016/01/26/defensive-programming.html>Shift-M</li> <li /2016/01/26/defensive-programming.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Defensive Programming via Validating Decorators</h1><aside class='book'>book coverRead more about this subject in Section 5.2
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Do you check the input parameters of your methods for validity? I don’t. I used to, but not anymore. I just let my methods crash with a null pointer and other exceptions when parameters are not valid. This may sound illogical, but only in the beginning. I’m suggesting you use validating decorators instead.</p>
Shi mian mai fu (2004) by Yimou Zhang<figcaption id="7c52eb30">Shi mian mai fu (2004) by Yimou Zhang</figcaption>
<p>Let’s take a look at this rather typical Java example:</p>
<pre>class Report { void export(File file) { if (file == null) { throw new IllegalArgumentException( "File is NULL; can't export." ); } if (file.exists()) { throw new IllegalArgumentException( "File already exists." ); } // Export the report to the file } }</pre>
<p>Pretty defensive, right? If we remove these validations, the code will be much shorter, but it will crash with rather confusing messages if NULL is provided by the client. Moreover, if the file already exists, our Report will silently overwrite it. Pretty dangerous, right?</p><p>Yes, we must protect ourselves, and we must be defensive.</p><p>But not this way, not by bloating the class with validations that have nothing to do with its core functionality. Instead, we should use decorators to do the validation. Here is how. First, there must be an interface Report:</p>
<pre>interface Report { void export(File file); }</pre>
<p>Then, a class that implements the core functionality:</p>
<pre>class DefaultReport implements Report { @Override void export(File file) { // Export the report to the file } }</pre>
<p>And, finally, a number of decorators that will protect us:</p>
<pre>class NoWriteOverReport implements Report { private final Report origin; NoWriteOverReport(Report rep) { this.origin = rep; } @Override void export(File file) { if (file.exists()) { throw new IllegalArgumentException( "File already exists." ); } this.origin.export(file); } }</pre>
<p>Now, the client has the flexibility of composing a complex object from decorators that perform their specific tasks. The core object will do the reporting, while the decorators will validate parameters:</p>
<pre>Report report = new NoNullReport( new NoWriteOverReport( new DefaultReport() ) ); report.export(file);</pre>
<p>What do we achieve with this approach? First and foremost: smaller objects. And smaller objects always mean higher maintainability. Our DefaultReport class will always remain small, no matter how many validations we may invent in the future. The more things we need to validate, the more validating decorators we will create. All of them will be small and cohesive. And we’ll be able to put them together in different variations.</p><p>Besides that, this approach makes our code much more reusable, as classes perform very few operations and don’t defend themselves by default. While being defensive is an important feature, we’ll use validating decorators. But this will not always be the case. Sometimes validation is just too expensive in terms of time and memory, and we may want to work directly with objects that don’t defend themselves.</p><p>I also decided not to use the Java Validation API anymore for the same reason. Its annotations make classes much more verbose and less cohesive. I’m using validating decorators instead.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Do you check the input parameters of your methods for validity? I don’t. I used to, but not anymore. I just let my methods crash with a null pointer and other exceptions when parameters are not valid. This may sound illogical, but only in the beginning. I’m suggesting you use validating decorators instead.</p>
Shi mian mai fu (2004) by Yimou Zhang<figcaption id="7c52eb30">Shi mian mai fu (2004) by Yimou Zhang</figcaption>
<p>Let’s take a look at this rather typical Java example:</p>
<pre>class Report { void export(File file) { if (file == null) { throw new IllegalArgumentException( "File is NULL; can't export." ); } if (file.exists()) { throw new IllegalArgumentException( "File already exists." ); } // Export the report to the file } }</pre>
<p>Pretty defensive, right? If we remove these validations, the code will be much shorter, but it will crash with rather confusing messages if NULL is provided by the client. Moreover, if the file already exists, our Report will silently overwrite it. Pretty dangerous, right?</p><p>Yes, we must protect ourselves, and we must be defensive.</p><p>But not this way, not by bloating the class with validations that have nothing to do with its core functionality. Instead, we should use decorators to do the validation. Here is how. First, there must be an interface Report:</p>
<pre>interface Report { void export(File file); }</pre>
<p>Then, a class that implements the core functionality:</p>
<pre>class DefaultReport implements Report { @Override void export(File file) { // Export the report to the file } }</pre>
<p>And, finally, a number of decorators that will protect us:</p>
<pre>class NoWriteOverReport implements Report { private final Report origin; NoWriteOverReport(Report rep) { this.origin = rep; } @Override void export(File file) { if (file.exists()) { throw new IllegalArgumentException( "File already exists." ); } this.origin.export(file); } }</pre>
<p>Now, the client has the flexibility of composing a complex object from decorators that perform their specific tasks. The core object will do the reporting, while the decorators will validate parameters:</p>
<pre>Report report = new NoNullReport( new NoWriteOverReport( new DefaultReport() ) ); report.export(file);</pre>
<p>What do we achieve with this approach? First and foremost: smaller objects. And smaller objects always mean higher maintainability. Our DefaultReport class will always remain small, no matter how many validations we may invent in the future. The more things we need to validate, the more validating decorators we will create. All of them will be small and cohesive. And we’ll be able to put them together in different variations.</p><p>Besides that, this approach makes our code much more reusable, as classes perform very few operations and don’t defend themselves by default. While being defensive is an important feature, we’ll use validating decorators. But this will not always be the case. Sometimes validation is just too expensive in terms of time and memory, and we may want to work directly with objects that don’t defend themselves.</p><p>I also decided not to use the Java Validation API anymore for the same reason. Its annotations make classes much more verbose and less cohesive. I’m using validating decorators instead.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Good Programmers Don't Work for Equity </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>12 Best</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>All 292</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Webinars</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Talks</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Books</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Papers</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Pets</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html class=”highlighted”>Trainings</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Award</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Testimonials</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Shift-M</li> <li /2016/01/12/good-programmers-dont-work-for-equity.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Good Programmers Don’t Work for Equity</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Los Angeles, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>“You’re a good programmer. I’m a great entrepreneur. This is a breakthrough idea. Help me build it. I don’t have cash, but I will give you equity. Deal?” I hear this at least once a month, and I always say no. Not because I don’t like your idea. Indeed, it is really interesting. And not because I’m too busy. I would definitely find time for a good idea. It’s not that. I say no because I don’t think you’re a good entrepreneur.</p>
Combien tu m'aimes? (2005) by Bertrand Blier<figcaption id="74a39f1f">Combien tu m'aimes? (2005) by Bertrand Blier</figcaption>
<p>So you want a good programmer to build your product. Or maybe a group of good programmers. And you are ready to give me some equity in exchange. That’s reasonable.</p><aside class="quote">You’re a good entrepreneur, right? How come you don’t have money, then?</aside><p>But what is your part of the deal?</p><p>How much are you putting on the table?</p><p>You say that you’re a good entrepreneur, right? How come you don’t have money, then? How come you can’t find someone to pay for the work of a good programmer?</p><p>I will create a product for you, but you will most certainly fail. You already failed. You failed to find initial investment to cover the startup expenses of the business. Why do you think you will succeed after the product is ready?</p><p>The point is that a good programmer will never work for equity. Not because a good programmer is greedy, or doesn’t want to risk, or doesn’t believe in new ideas. Not at all.</p><p>A good programmer wants to work with a good entrepreneur. And a good entrepreneur knows how to find money. That’s the definition of a decent entrepreneur.</p><p>Period.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>“You’re a good programmer. I’m a great entrepreneur. This is a breakthrough idea. Help me build it. I don’t have cash, but I will give you equity. Deal?” I hear this at least once a month, and I always say no. Not because I don’t like your idea. Indeed, it is really interesting. And not because I’m too busy. I would definitely find time for a good idea. It’s not that. I say no because I don’t think you’re a good entrepreneur.</p>
Combien tu m'aimes? (2005) by Bertrand Blier<figcaption id="74a39f1f">Combien tu m'aimes? (2005) by Bertrand Blier</figcaption>
<p>So you want a good programmer to build your product. Or maybe a group of good programmers. And you are ready to give me some equity in exchange. That’s reasonable.</p><aside class="quote">You’re a good entrepreneur, right? How come you don’t have money, then?</aside><p>But what is your part of the deal?</p><p>How much are you putting on the table?</p><p>You say that you’re a good entrepreneur, right? How come you don’t have money, then? How come you can’t find someone to pay for the work of a good programmer?</p><p>I will create a product for you, but you will most certainly fail. You already failed. You failed to find initial investment to cover the startup expenses of the business. Why do you think you will succeed after the product is ready?</p><p>The point is that a good programmer will never work for equity. Not because a good programmer is greedy, or doesn’t want to risk, or doesn’t believe in new ideas. Not at all.</p><p>A good programmer wants to work with a good entrepreneur. And a good entrepreneur knows how to find money. That’s the definition of a decent entrepreneur.</p><p>Period.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Temporal Coupling Between Method Calls </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>12 Best</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>All 292</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Webinars</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Talks</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Books</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Papers</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Pets</li> <li /2015/12/08/temporal-coupling-between-method-calls.html class=”highlighted”>Trainings</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Award</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Testimonials</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Shift-M</li> <li /2015/12/08/temporal-coupling-between-method-calls.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Temporal Coupling Between Method Calls</h1><aside class='book'>book coverRead more about this subject in Section 5.6
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Kiev, Ukraine</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Temporal coupling happens between sequential method calls when they must stay in a particular order. This is inevitable in imperative programming, but we can reduce the negative effect of it just by turning those static procedures into functions. Take a look at this example.</p>
Blueberry (2004) by Jan Kounen<figcaption id="17ff3e16">Blueberry (2004) by Jan Kounen</figcaption>
<p>Here is the code:</p>
<pre>class Foo { public List<String> names() { List<String> list = new LinkedList(); Foo.append(list, "Jeff"); Foo.append(list, "Walter"); return list; } private static void append( List<String> list, String item) { list.add(item.toLowerCase()); } }</pre>
<p>What do you think about that? I believe it’s clear what names() is doing—creating a list of names. In order to avoid duplication, there is a supplementary procedure, append(), which converts an item to lowercase and adds it to the list.</p><p>This is poor design.</p><p>It is a procedural design, and there is temporal coupling between lines in method names().</p><p>Let me first show you a better (though not the best!) design, then I will try to explain its benefits:</p>
<pre>class Foo { public List<String> names() { return Foo.with( Foo.with( new LinkedList(), "Jeff" ), "Walter" ); } private static List<String> with( List<String> list, String item) { list.add(item.toLowerCase()); return list; } }</pre>
<p>An ideal design for method with() would create a new instance of List, populate it through addAll(list), then add(item) to it, and finally return. That would be perfectly immutable, but slow.</p><p>So, what is wrong with this:</p>
<pre>List<String> list = new LinkedList(); Foo.append(list, "Jeff"); Foo.append(list, "Walter"); return list;</pre>
<p>It looks perfectly clean, doesn’t it? Instantiate a list, append two items to it, and return it. Yes, it is clean—for now. Because we remember what append() is doing. In a few months, we’ll get back to this code, and it will look like this:</p>
<pre>List<String> list = new LinkedList(); // 10 more lines here Foo.append(list, "Jeff"); Foo.append(list, "Walter"); // 10 more lines here return list;</pre>
<p>Is it so clear now that append() is actually adding "Jeff" to list? What will happen if I remove that line? Will it affect the result being returned in the last line? I don’t know. I need to check the body of method append() to make sure.</p><p>Also, how about returning list first and calling append() afterwards? This is what possible “refactoring” may do to our code:</p>
<pre>List<String> list = new LinkedList(); if (/* something */) { return list; } // 10 more lines here Foo.append(list, "Walter"); Foo.append(list, "Jeff"); // 10 more lines here return list;</pre>
<p>First of all, we return list too early, when it is not ready. But did anyone tell me that these two calls to append() must happen before return list? Second, we changed the order of append() calls. Again, did anyone tell me that it’s important to call them in that particular order?</p><p>Nobody. Nowhere. This is called temporal coupling.</p><p>Our lines are coupled together. They must stay in this particular order, but the knowledge about that order is hidden. It’s easy to destroy the order, and our compiler won’t be able to catch us.</p><p>To the contrary, this design doesn’t have any “order”:</p>
<pre>return Foo.with( Foo.with( new LinkedList(), "Jeff" ), "Walter" );</pre>
<p>It just returns a list, which is constructed by a few calls to the with() method. It is a single line instead of four.</p><p>As discussed before, an ideal method in OOP must have just a single statement, and this statement is return.</p><p>The same is true about validation. For example, this code is bad:</p>
<pre>list.add("Jeff"); Foo.checkIfListStillHasSpace(list); list.add("Walter");</pre>
<p>While this one is much better:</p>
<pre>list.add("Jeff"); Foo.withEnoughSpace(list).add("Walter");</pre>
<p>See the difference?</p><p>And, of course, an ideal approach would be to use composable decorators instead of these ugly static methods. But if it’s not possible for some reason, just don’t make those static methods look like procedures. Make sure they always return results, which become arguments to further calls.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Temporal coupling happens between sequential method calls when they must stay in a particular order. This is inevitable in imperative programming, but we can reduce the negative effect of it just by turning those static procedures into functions. Take a look at this example.</p>
Blueberry (2004) by Jan Kounen<figcaption id="17ff3e16">Blueberry (2004) by Jan Kounen</figcaption>
<p>Here is the code:</p>
<pre>class Foo { public List<String> names() { List<String> list = new LinkedList(); Foo.append(list, "Jeff"); Foo.append(list, "Walter"); return list; } private static void append( List<String> list, String item) { list.add(item.toLowerCase()); } }</pre>
<p>What do you think about that? I believe it’s clear what names() is doing—creating a list of names. In order to avoid duplication, there is a supplementary procedure, append(), which converts an item to lowercase and adds it to the list.</p><p>This is poor design.</p><p>It is a procedural design, and there is temporal coupling between lines in method names().</p><p>Let me first show you a better (though not the best!) design, then I will try to explain its benefits:</p>
<pre>class Foo { public List<String> names() { return Foo.with( Foo.with( new LinkedList(), "Jeff" ), "Walter" ); } private static List<String> with( List<String> list, String item) { list.add(item.toLowerCase()); return list; } }</pre>
<p>An ideal design for method with() would create a new instance of List, populate it through addAll(list), then add(item) to it, and finally return. That would be perfectly immutable, but slow.</p><p>So, what is wrong with this:</p>
<pre>List<String> list = new LinkedList(); Foo.append(list, "Jeff"); Foo.append(list, "Walter"); return list;</pre>
<p>It looks perfectly clean, doesn’t it? Instantiate a list, append two items to it, and return it. Yes, it is clean—for now. Because we remember what append() is doing. In a few months, we’ll get back to this code, and it will look like this:</p>
<pre>List<String> list = new LinkedList(); // 10 more lines here Foo.append(list, "Jeff"); Foo.append(list, "Walter"); // 10 more lines here return list;</pre>
<p>Is it so clear now that append() is actually adding "Jeff" to list? What will happen if I remove that line? Will it affect the result being returned in the last line? I don’t know. I need to check the body of method append() to make sure.</p><p>Also, how about returning list first and calling append() afterwards? This is what possible “refactoring” may do to our code:</p>
<pre>List<String> list = new LinkedList(); if (/* something */) { return list; } // 10 more lines here Foo.append(list, "Walter"); Foo.append(list, "Jeff"); // 10 more lines here return list;</pre>
<p>First of all, we return list too early, when it is not ready. But did anyone tell me that these two calls to append() must happen before return list? Second, we changed the order of append() calls. Again, did anyone tell me that it’s important to call them in that particular order?</p><p>Nobody. Nowhere. This is called temporal coupling.</p><p>Our lines are coupled together. They must stay in this particular order, but the knowledge about that order is hidden. It’s easy to destroy the order, and our compiler won’t be able to catch us.</p><p>To the contrary, this design doesn’t have any “order”:</p>
<pre>return Foo.with( Foo.with( new LinkedList(), "Jeff" ), "Walter" );</pre>
<p>It just returns a list, which is constructed by a few calls to the with() method. It is a single line instead of four.</p><p>As discussed before, an ideal method in OOP must have just a single statement, and this statement is return.</p><p>The same is true about validation. For example, this code is bad:</p>
<pre>list.add("Jeff"); Foo.checkIfListStillHasSpace(list); list.add("Walter");</pre>
<p>While this one is much better:</p>
<pre>list.add("Jeff"); Foo.withEnoughSpace(list).add("Walter");</pre>
<p>See the difference?</p><p>And, of course, an ideal approach would be to use composable decorators instead of these ugly static methods. But if it’s not possible for some reason, just don’t make those static methods look like procedures. Make sure they always return results, which become arguments to further calls.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Throwing an Exception Without Proper Context Is a Bad Habit </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/12/01/rethrow-exceptions.html>12 Best</li> <li /2015/12/01/rethrow-exceptions.html>All 292</li> <li /2015/12/01/rethrow-exceptions.html>Webinars</li> <li /2015/12/01/rethrow-exceptions.html>Talks</li> <li /2015/12/01/rethrow-exceptions.html>Books</li> <li /2015/12/01/rethrow-exceptions.html>Papers</li> <li /2015/12/01/rethrow-exceptions.html>Pets</li> <li /2015/12/01/rethrow-exceptions.html class=”highlighted”>Trainings</li> <li /2015/12/01/rethrow-exceptions.html>Award</li> <li /2015/12/01/rethrow-exceptions.html>Testimonials</li> <li /2015/12/01/rethrow-exceptions.html>Shift-M</li> <li /2015/12/01/rethrow-exceptions.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Throwing an Exception Without Proper Context Is a Bad Habit</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">San Jose, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>I keep repeating the same mistake again and again. So it’s time to stop and make a rule to prevent this from happening anymore. The mistake is not fatal, but it’s very annoying. When I look at production logs, I often see something like "File doesn't exist", and I ask myself: What file? Where is it supposed to exist? What did the server try to do with it? What was going on a second before it crashed? There is no answer in the log, and it’s totally my fault. I either 1) don’t re-throw or 2) re-throw without providing context. Both are wrong.</p>
Four Rooms (1995) by Allison Anders et al.<figcaption id="ddf945c0">Four Rooms (1995) by Allison Anders et al.</figcaption>
<p>This is how the code may look:</p>
<pre>if (!file.exists()) { throw new IllegalArgumentException( "File doesn't exist" ); }</pre>
<p>It may also look like this:</p>
<pre>try { Files.delete(file); } catch (IOException ex) { throw new IllegalArgumentException(ex); }</pre>
<p>Both examples demonstrate an inadequate style of handling situations that involve exceptions and reporting them. What’s wrong here? The exception messages are not thorough enough. They simply don’t contain any information from the place where they originated from.</p><p>This is how they should look instead:</p>
<pre>if (!file.exists()) { throw new IllegalArgumentException( String.format( "User profile file %s doesn't exist", file.getAbsolutePath() ) ); }</pre>
<p>And the second example should look like this:</p>
<pre>try { Files.delete(file); } catch (IOException ex) { throw new IllegalArgumentException( String.format( "Can't delete user profile data file %s", file.getAbsolutePath() ), ex ); }</pre>
<p>See the difference? This may look like redundant code, but it’s not. Of course, when I’m writing all this, I don’t really care about logs and exceptions. I’m not really expecting this file to be absent.</p><p>But I should.</p><p>There should be a rule: Every time we throw or re-throw, an exception message must describe the problem with as much detail as possible.</p><p>Of course, we can’t forget about security and risk putting any sensitive information into the exception message, like passwords, credit card numbers, etc. Besides that, as much as possible must be exposed to the exception catcher at a higher level.</p><p>Throwing an exception is literally an escalation of a problem to a higher level of management. Imagine that my boss is asking me to install a new server. I come back to him in a few hours and say, “I failed; sorry.” That would sound strange. He would ask for more details. Why did I fail? What exactly went wrong? Is it possible to do it differently? Etc.</p><p>Such code is literally a sign of disrespect to the client:</p>
<pre>throw new IllegalArgumentException( "File doesn't exist" );</pre>
<p>I have to be more verbose and give more details.</p><p>And I’m not alone in this mistake. I see it everywhere, and it really makes debugging difficult, especially in production, where it’s almost impossible to reproduce the problem right away.</p><p>Thus, please be more verbose in your exception messages. I will do the same in my code :)</p><p>And one more thing before you go. In most OOP languages, exceptions are unchecked, which means that catching them is not a mandatory operation, unfortunately. Nevertheless, I recommend you catch, add context, and re-throw them all, always. This may seem like pure noise, but it’s not! Just make your methods smaller and ensure all exceptions sent out of them have enough information about their origins. You will do yourself and everybody else a big favor.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>I keep repeating the same mistake again and again. So it’s time to stop and make a rule to prevent this from happening anymore. The mistake is not fatal, but it’s very annoying. When I look at production logs, I often see something like "File doesn't exist", and I ask myself: What file? Where is it supposed to exist? What did the server try to do with it? What was going on a second before it crashed? There is no answer in the log, and it’s totally my fault. I either 1) don’t re-throw or 2) re-throw without providing context. Both are wrong.</p>
Four Rooms (1995) by Allison Anders et al.<figcaption id="ddf945c0">Four Rooms (1995) by Allison Anders et al.</figcaption>
<p>This is how the code may look:</p>
<pre>if (!file.exists()) { throw new IllegalArgumentException( "File doesn't exist" ); }</pre>
<p>It may also look like this:</p>
<pre>try { Files.delete(file); } catch (IOException ex) { throw new IllegalArgumentException(ex); }</pre>
<p>Both examples demonstrate an inadequate style of handling situations that involve exceptions and reporting them. What’s wrong here? The exception messages are not thorough enough. They simply don’t contain any information from the place where they originated from.</p><p>This is how they should look instead:</p>
<pre>if (!file.exists()) { throw new IllegalArgumentException( String.format( "User profile file %s doesn't exist", file.getAbsolutePath() ) ); }</pre>
<p>And the second example should look like this:</p>
<pre>try { Files.delete(file); } catch (IOException ex) { throw new IllegalArgumentException( String.format( "Can't delete user profile data file %s", file.getAbsolutePath() ), ex ); }</pre>
<p>See the difference? This may look like redundant code, but it’s not. Of course, when I’m writing all this, I don’t really care about logs and exceptions. I’m not really expecting this file to be absent.</p><p>But I should.</p><p>There should be a rule: Every time we throw or re-throw, an exception message must describe the problem with as much detail as possible.</p><p>Of course, we can’t forget about security and risk putting any sensitive information into the exception message, like passwords, credit card numbers, etc. Besides that, as much as possible must be exposed to the exception catcher at a higher level.</p><p>Throwing an exception is literally an escalation of a problem to a higher level of management. Imagine that my boss is asking me to install a new server. I come back to him in a few hours and say, “I failed; sorry.” That would sound strange. He would ask for more details. Why did I fail? What exactly went wrong? Is it possible to do it differently? Etc.</p><p>Such code is literally a sign of disrespect to the client:</p>
<pre>throw new IllegalArgumentException( "File doesn't exist" );</pre>
<p>I have to be more verbose and give more details.</p><p>And I’m not alone in this mistake. I see it everywhere, and it really makes debugging difficult, especially in production, where it’s almost impossible to reproduce the problem right away.</p><p>Thus, please be more verbose in your exception messages. I will do the same in my code :)</p><p>And one more thing before you go. In most OOP languages, exceptions are unchecked, which means that catching them is not a mandatory operation, unfortunately. Nevertheless, I recommend you catch, add context, and re-throw them all, always. This may seem like pure noise, but it’s not! Just make your methods smaller and ensure all exceptions sent out of them have enough information about their origins. You will do yourself and everybody else a big favor.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Vertical and Horizontal Decorating </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/10/01/vertical-horizontal-decorating.html>12 Best</li> <li /2015/10/01/vertical-horizontal-decorating.html>All 292</li> <li /2015/10/01/vertical-horizontal-decorating.html>Webinars</li> <li /2015/10/01/vertical-horizontal-decorating.html>Talks</li> <li /2015/10/01/vertical-horizontal-decorating.html>Books</li> <li /2015/10/01/vertical-horizontal-decorating.html>Papers</li> <li /2015/10/01/vertical-horizontal-decorating.html>Pets</li> <li /2015/10/01/vertical-horizontal-decorating.html class=”highlighted”>Trainings</li> <li /2015/10/01/vertical-horizontal-decorating.html>Award</li> <li /2015/10/01/vertical-horizontal-decorating.html>Testimonials</li> <li /2015/10/01/vertical-horizontal-decorating.html>Shift-M</li> <li /2015/10/01/vertical-horizontal-decorating.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Vertical and Horizontal Decorating</h1><aside class='book'>book coverRead more about this subject in Section 3.2.6
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Moscow, Russia</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>A decorator pattern is one of the best ways to add features to an object without changing its interface. I use composable decorators quite often and always question myself as to how to design them right when the list of features must be configurable. I’m not sure I have the right answer, but here is some food for thought.</p>
The Apartment (1960) by Billy Wilder<figcaption id="3406debc">The Apartment (1960) by Billy Wilder</figcaption>
<p>Let’s say I have a list of numbers:</p>
<pre>interface Numbers { Iterable<Integer> iterate(); }</pre>
<p>Now I want to create a list that will only have odd, unique, positive, and sorted numbers. The first approach is vertical (I just made this name up):</p>
<pre>Numbers numbers = new Sorted( new Unique( new Odds( new Positive( new ArrayNumbers( new Integer[] { -1, 78, 4, -34, 98, 4, } ) ) ) ) );</pre>
<p>The second approach is horizontal (again, a name I made up):</p>
<pre>Numbers numbers = new Modified( new ArrayNumbers( new Integer[] { -1, 78, 4, -34, 98, 4, } ), new Diff[] { new Positive(), new Odds(), new Unique(), new Sorted(), } );</pre>
<p>See the difference? The first approach decorates ArrayNumbers “vertically,” adding functionality through the composable decorators Positive, Odds, Unique, and Sorted.</p><p>The second approach introduces the new interface Diff, which implements the core functionality of iterating numbers through instances of Positive, Odds, Unique, and Sorted:</p>
<pre>interface Diff { Iterable<Integer> apply(Iterable<Integer> origin); }</pre>
<p>For the user of numbers, both approaches are the same. The difference is only in the design. Which one is better and when? It seems that vertical decorating is easier to implement and is more suitable for smaller objects that expose just a few methods.</p><p>As for my experience, I always tend to start with vertical decorating since it’s easier to implement but eventually migrate to a horizontal one when the number of decorators starts to grow.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>A decorator pattern is one of the best ways to add features to an object without changing its interface. I use composable decorators quite often and always question myself as to how to design them right when the list of features must be configurable. I’m not sure I have the right answer, but here is some food for thought.</p>
The Apartment (1960) by Billy Wilder<figcaption id="3406debc">The Apartment (1960) by Billy Wilder</figcaption>
<p>Let’s say I have a list of numbers:</p>
<pre>interface Numbers { Iterable<Integer> iterate(); }</pre>
<p>Now I want to create a list that will only have odd, unique, positive, and sorted numbers. The first approach is vertical (I just made this name up):</p>
<pre>Numbers numbers = new Sorted( new Unique( new Odds( new Positive( new ArrayNumbers( new Integer[] { -1, 78, 4, -34, 98, 4, } ) ) ) ) );</pre>
<p>The second approach is horizontal (again, a name I made up):</p>
<pre>Numbers numbers = new Modified( new ArrayNumbers( new Integer[] { -1, 78, 4, -34, 98, 4, } ), new Diff[] { new Positive(), new Odds(), new Unique(), new Sorted(), } );</pre>
<p>See the difference? The first approach decorates ArrayNumbers “vertically,” adding functionality through the composable decorators Positive, Odds, Unique, and Sorted.</p><p>The second approach introduces the new interface Diff, which implements the core functionality of iterating numbers through instances of Positive, Odds, Unique, and Sorted:</p>
<pre>interface Diff { Iterable<Integer> apply(Iterable<Integer> origin); }</pre>
<p>For the user of numbers, both approaches are the same. The difference is only in the design. Which one is better and when? It seems that vertical decorating is easier to implement and is more suitable for smaller objects that expose just a few methods.</p><p>As for my experience, I always tend to start with vertical decorating since it’s easier to implement but eventually migrate to a horizontal one when the number of decorators starts to grow.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> When Do You Stop Testing? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/09/10/testing-exit-criteria.html>12 Best</li> <li /2015/09/10/testing-exit-criteria.html>All 292</li> <li /2015/09/10/testing-exit-criteria.html>Webinars</li> <li /2015/09/10/testing-exit-criteria.html>Talks</li> <li /2015/09/10/testing-exit-criteria.html>Books</li> <li /2015/09/10/testing-exit-criteria.html>Papers</li> <li /2015/09/10/testing-exit-criteria.html>Pets</li> <li /2015/09/10/testing-exit-criteria.html class=”highlighted”>Trainings</li> <li /2015/09/10/testing-exit-criteria.html>Award</li> <li /2015/09/10/testing-exit-criteria.html>Testimonials</li> <li /2015/09/10/testing-exit-criteria.html>Shift-M</li> <li /2015/09/10/testing-exit-criteria.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">When Do You Stop Testing?</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Moscow, Russia</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Republished in:</li> <li>BLOG@CACM</li></ul><p class="unprintable"><p>There is a software to be tested. There is a team of testers. There is some money in the budget. There is some time in the schedule. We start right now. Testers are trying to break the product, finding bugs, reporting bugs, communicating with programmers when necessary, doing their best to find what’s wrong. Eventually they stop and say “we’re done.” How do they know when to stop? When there is enough testing? It’s obvious—when there are no more bugs left and the product can be shipped! If you think like this, I have bad news for you. You’re fundamentally wrong.</p>
La fille sur le pont (1999) by Patrice Leconte<figcaption id="3e0b5dd3">La fille sur le pont (1999) by Patrice Leconte</figcaption>
<p>All this is perfectly explained by Glenford Myers in his great book The Art of Software Testing. I will just summarize it here again.</p>
badge
<p>First, “testing is the process of executing a program with the intent of finding errors” (page 6). Pay attention, the intent is to find errors. Not to prove that the product works fine, but to prove that it doesn’t work as intended. The goal of any tester is to show how the product can be broken, how it fails on different inputs, how it crashes under stress, how it misunderstands the user, how it doesn’t satisfy the requirements. This is why Dr. Myers is calling testing “a destructive, even sadistic, process” (page 6). This is what most testers don’t understand.</p><aside class="youtube"> <div class="box"> YouTube video #wd-SA1HVmLg<div class="play"></div></div><div>How Do You Know When Your Product is Ready to be Shipped?; 18 November 2016.</div></aside><p>Second, any software has an unlimited amount of bugs. Dr. Myers says that “you cannot test a program to guarantee that it is error free” (page 10) and that “it is impractical, often impossible, to find all the errors in a program” (page 8). This is also what most testers don’t understand. They believe that there is a limited number of bugs, which they have to find and call it a day. There literally no limit! The amount of bugs is unlimited, in any software product. No matter how small or big, complex or simple, new or old is the product.</p><aside class="quote">They can’t find all bugs, no matter how much time we give them</aside><p>Having these axioms in mind, let’s try to decide when testers have to stop. According to Dr. Myers, “one of the most difficult questions to answer when testing a program is determining when to stop, since there is no way of knowing if the error just detected is the last remaining error” (page 135).</p><p>They can’t find all bugs, no matter how much time we give them. And they are motivated to find more and more of them. But at some point of time we must make a decision and release the product. Looks like we will release it with bugs inside? Yes, indeed! We will release a product full of bugs. The only question is how many of them were found already and how critical they were.</p><p>Let’s put it all together. There are too many bugs to be able to find all of them in a reasonable amount of time. However, we have to release a new version, sooner or later. At the same time, testers will always tell us that there are more bugs there and they can find more, just need more time. What to do?</p><p>Dr. Myers says that “since the goal of testing is to find errors, why not make the completion criterion the detection of some predefined number of errors?” (page 136). Indeed, we should predict how many bugs are just enough to find, in order to have a desirable level of confidence that the product is ready to be shipped. Then, ship it, consciously understanding that it still has an unlimited amount of not yet discovered bugs.</p>
badge
<p>David West in Object Thinking says that “software is released for use, not when it is known to be correct, but when the rate of discovering errors slows down to one that management considers acceptable” (page 13).</p><p>Thus, the only valid criteria for exiting a testing process is the discovery of a forecast amount of bugs.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>There is a software to be tested. There is a team of testers. There is some money in the budget. There is some time in the schedule. We start right now. Testers are trying to break the product, finding bugs, reporting bugs, communicating with programmers when necessary, doing their best to find what’s wrong. Eventually they stop and say “we’re done.” How do they know when to stop? When there is enough testing? It’s obvious—when there are no more bugs left and the product can be shipped! If you think like this, I have bad news for you. You’re fundamentally wrong.</p>
La fille sur le pont (1999) by Patrice Leconte<figcaption id="3e0b5dd3">La fille sur le pont (1999) by Patrice Leconte</figcaption>
<p>All this is perfectly explained by Glenford Myers in his great book The Art of Software Testing. I will just summarize it here again.</p>
badge
<p>First, “testing is the process of executing a program with the intent of finding errors” (page 6). Pay attention, the intent is to find errors. Not to prove that the product works fine, but to prove that it doesn’t work as intended. The goal of any tester is to show how the product can be broken, how it fails on different inputs, how it crashes under stress, how it misunderstands the user, how it doesn’t satisfy the requirements. This is why Dr. Myers is calling testing “a destructive, even sadistic, process” (page 6). This is what most testers don’t understand.</p><aside class="youtube"> <div class="box"> YouTube video #wd-SA1HVmLg<div class="play"></div></div><div>How Do You Know When Your Product is Ready to be Shipped?; 18 November 2016.</div></aside><p>Second, any software has an unlimited amount of bugs. Dr. Myers says that “you cannot test a program to guarantee that it is error free” (page 10) and that “it is impractical, often impossible, to find all the errors in a program” (page 8). This is also what most testers don’t understand. They believe that there is a limited number of bugs, which they have to find and call it a day. There literally no limit! The amount of bugs is unlimited, in any software product. No matter how small or big, complex or simple, new or old is the product.</p><aside class="quote">They can’t find all bugs, no matter how much time we give them</aside><p>Having these axioms in mind, let’s try to decide when testers have to stop. According to Dr. Myers, “one of the most difficult questions to answer when testing a program is determining when to stop, since there is no way of knowing if the error just detected is the last remaining error” (page 135).</p><p>They can’t find all bugs, no matter how much time we give them. And they are motivated to find more and more of them. But at some point of time we must make a decision and release the product. Looks like we will release it with bugs inside? Yes, indeed! We will release a product full of bugs. The only question is how many of them were found already and how critical they were.</p><p>Let’s put it all together. There are too many bugs to be able to find all of them in a reasonable amount of time. However, we have to release a new version, sooner or later. At the same time, testers will always tell us that there are more bugs there and they can find more, just need more time. What to do?</p><p>Dr. Myers says that “since the goal of testing is to find errors, why not make the completion criterion the detection of some predefined number of errors?” (page 136). Indeed, we should predict how many bugs are just enough to find, in order to have a desirable level of confidence that the product is ready to be shipped. Then, ship it, consciously understanding that it still has an unlimited amount of not yet discovered bugs.</p>
badge
<p>David West in Object Thinking says that “software is released for use, not when it is known to be correct, but when the rate of discovering errors slows down to one that management considers acceptable” (page 13).</p><p>Thus, the only valid criteria for exiting a testing process is the discovery of a forecast amount of bugs.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Need Robust Software? Make It Fragile </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/08/25/fail-fast.html>12 Best</li> <li /2015/08/25/fail-fast.html>All 292</li> <li /2015/08/25/fail-fast.html>Webinars</li> <li /2015/08/25/fail-fast.html>Talks</li> <li /2015/08/25/fail-fast.html>Books</li> <li /2015/08/25/fail-fast.html>Papers</li> <li /2015/08/25/fail-fast.html>Pets</li> <li /2015/08/25/fail-fast.html class=”highlighted”>Trainings</li> <li /2015/08/25/fail-fast.html>Award</li> <li /2015/08/25/fail-fast.html>Testimonials</li> <li /2015/08/25/fail-fast.html>Shift-M</li> <li /2015/08/25/fail-fast.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Need Robust Software? Make It Fragile</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Dnipro, Ukraine</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>In any software project, the goal is to create something stable. We don’t want it to break in front of a user. We also don’t want our website to show an “internal application error” instead of a web page. We want our software to work, not fail. That’s a perfectly valid and logical desire, but in order to achieve that, we have to make our software as fragile as possible. This may sound counter-intuitive, but that’s the way it is. The more fragile your app is in development, the more robust it is in production.</p>
Black Cat, White Cat (1998) by Emir Kusturica<figcaption id="28b040eb">Black Cat, White Cat (1998) by Emir Kusturica</figcaption>
<p>By fragile, I’m referring to the Fail Fast philosophy, which is the opposite of Fail Safe. I believe you know the difference, but let me remind you anyway, by example. This is Fail Safe:</p>
<pre>public int size(File file) { if (!file.exists()) { return 0; } return file.length(); }</pre>
<aside class="youtube"> <div class="box"> YouTube video #QMcDa2eyRBY<div class="play"></div></div><div>Need Robust Software? Make It Fragile; 29 February 2016.</div></aside><p>This method is supposed to calculate and return a file size. It first checks whether the file exists. If it doesn’t exist, the method returns zero. Indeed, the file is absent, so there is no size. We could complain that the file is absent, but what for? Why make noise? Let’s keep it quiet and return zero. We don’t fail because we’re trying to keep the app running. This is called Fail Safe.</p><p>To the contrary, this is how Fail Fast looks:</p>
<pre>public int size(File file) { if (!file.exists()) { throw new IllegalArgumentException( "There is no such file; I can't get its length." ); } return file.length(); }</pre>
<p>We can’t find a file? We don’t hide this fact. We make this situation public and visible. We scream and cry. We throw an exception. We want the app to crash, break, and fail, because someone gave us a file that doesn’t exist. We complain and protest. This is called Fail Fast.</p><aside class="quote">Fail Safe approach conceals problems and makes code less maintainable, and that’s why it’s difficult to stabilize</aside><p>Which philosophy, if we follow it everywhere, will make our software robust and failure-resilient? Only the second one—the Fail Fast.</p><p>Why? Because the quicker and easier the failure is, the faster it will be fixed. And the fix will be simpler and also more visible. Fail Fast is a much better approach for maintainability. The code becomes cleaner. It is much easier to track a failure. All methods are ready to break and throw an exception on even the tiniest problem.</p><aside class="youtube"> <div class="box"> YouTube video #nCGBgI1MNwE<div class="play"></div></div><div>Need It Robust? Make It Fragile!; 21 May 2016.</div></aside><p>In this example, if the method returns zero, it’s not obvious whether the file exists and its size is actually zero or if its name is wrong and it is just not found. The Fail Safe approach conceals problems and makes code less maintainable, and that’s why it’s difficult to stabilize.</p><p>In the beginning, during production, we will have many crashes and errors. But all of them will be visible and easy to understand. We will fix them and cover them with unit tests. Each fix will make our software more stable and better covered by tests.</p><p>Software designed with the Fail Safe approach in mind will look more stable at the beginning, but it will degrade quickly and inevitably turn into an unmaintainable mess.</p><p>Software designed with the Fail Fast approach in mind will crash frequently at the beginning but will improve its stability with every fix and eventually become very stable and robust.</p><p>That’s why fragility is the key success factor for robustness.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>In any software project, the goal is to create something stable. We don’t want it to break in front of a user. We also don’t want our website to show an “internal application error” instead of a web page. We want our software to work, not fail. That’s a perfectly valid and logical desire, but in order to achieve that, we have to make our software as fragile as possible. This may sound counter-intuitive, but that’s the way it is. The more fragile your app is in development, the more robust it is in production.</p>
Black Cat, White Cat (1998) by Emir Kusturica<figcaption id="28b040eb">Black Cat, White Cat (1998) by Emir Kusturica</figcaption>
<p>By fragile, I’m referring to the Fail Fast philosophy, which is the opposite of Fail Safe. I believe you know the difference, but let me remind you anyway, by example. This is Fail Safe:</p>
<pre>public int size(File file) { if (!file.exists()) { return 0; } return file.length(); }</pre>
<aside class="youtube"> <div class="box"> YouTube video #QMcDa2eyRBY<div class="play"></div></div><div>Need Robust Software? Make It Fragile; 29 February 2016.</div></aside><p>This method is supposed to calculate and return a file size. It first checks whether the file exists. If it doesn’t exist, the method returns zero. Indeed, the file is absent, so there is no size. We could complain that the file is absent, but what for? Why make noise? Let’s keep it quiet and return zero. We don’t fail because we’re trying to keep the app running. This is called Fail Safe.</p><p>To the contrary, this is how Fail Fast looks:</p>
<pre>public int size(File file) { if (!file.exists()) { throw new IllegalArgumentException( "There is no such file; I can't get its length." ); } return file.length(); }</pre>
<p>We can’t find a file? We don’t hide this fact. We make this situation public and visible. We scream and cry. We throw an exception. We want the app to crash, break, and fail, because someone gave us a file that doesn’t exist. We complain and protest. This is called Fail Fast.</p><aside class="quote">Fail Safe approach conceals problems and makes code less maintainable, and that’s why it’s difficult to stabilize</aside><p>Which philosophy, if we follow it everywhere, will make our software robust and failure-resilient? Only the second one—the Fail Fast.</p><p>Why? Because the quicker and easier the failure is, the faster it will be fixed. And the fix will be simpler and also more visible. Fail Fast is a much better approach for maintainability. The code becomes cleaner. It is much easier to track a failure. All methods are ready to break and throw an exception on even the tiniest problem.</p><aside class="youtube"> <div class="box"> YouTube video #nCGBgI1MNwE<div class="play"></div></div><div>Need It Robust? Make It Fragile!; 21 May 2016.</div></aside><p>In this example, if the method returns zero, it’s not obvious whether the file exists and its size is actually zero or if its name is wrong and it is just not found. The Fail Safe approach conceals problems and makes code less maintainable, and that’s why it’s difficult to stabilize.</p><p>In the beginning, during production, we will have many crashes and errors. But all of them will be visible and easy to understand. We will fix them and cover them with unit tests. Each fix will make our software more stable and better covered by tests.</p><p>Software designed with the Fail Safe approach in mind will look more stable at the beginning, but it will degrade quickly and inevitably turn into an unmaintainable mess.</p><p>Software designed with the Fail Fast approach in mind will crash frequently at the beginning but will improve its stability with every fix and eventually become very stable and robust.</p><p>That’s why fragility is the key success factor for robustness.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Checked vs. Unchecked Exceptions: The Debate Is Not Over </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>12 Best</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>All 292</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Webinars</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Talks</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Books</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Papers</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Pets</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html class=”highlighted”>Trainings</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Award</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Testimonials</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Shift-M</li> <li /2015/07/28/checked-vs-unchecked-exceptions.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Checked vs. Unchecked Exceptions: The Debate Is Not Over</h1><aside class='book'>book coverRead more about this subject in Section 4.2
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Sunnyvale, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Do we need checked exceptions at all? The debate is over, isn’t it? Not for me. While most object-oriented languages don’t have them, and most programmers think checked exceptions are a Java mistake, I believe in the opposite—unchecked exceptions are the mistake. Moreover, I believe multiple exception types are a bad idea too.</p>
True Romance (1993) by Tony Scott<figcaption id="443dfa82">True Romance (1993) by Tony Scott</figcaption>
<p>Let me first explain how I understand exceptions in object-oriented programming. Then I’ll compare my understanding with a “traditional” approach, and we’ll discuss the differences. So, my understanding first.</p><p>Say there is a method that saves some binary data to a file:</p>
<pre>public void save(File file, byte[] data) throws Exception { // save data to the file }</pre>
<p>When everything goes right, the method just saves the data and returns control. When something is wrong, it throws Exception and we have to do something about it:</p>
<pre>try { save(file, data); } catch (Exception ex) { System.out.println("Sorry, we can't save right now."); }</pre>
<p>When a method says it throws an exception, I understand that the method is not safe. It may fail sometimes, and it’s my responsibility to either 1) handle this failure or 2) declare myself as unsafe too.</p><p>I know each method is designed with a single responsibility principle in mind. This is a guarantee to me that if method save() fails, it means the entire saving operation can’t be completed. If I need to know what the cause of this failure was, I will un-chain the exception—traverse the stack of chained exceptions and stack traces encapsulated in ex.</p><p>I never use exceptions for flow control, which means I never recover situations where exceptions are thrown. When an exception occurs, I let it float up to the highest level of the application. Sometimes I rethrow it in order to add more semantic information to the chain. That’s why it doesn’t matter to me what the cause of the exception thrown by save() was. I just know the method failed. That’s enough for me. Always.</p><p>For the same reason, I don’t need to differentiate between different exception types. I just don’t need that type of hierarchy. Exception is enough for me. Again, that’s because I don’t use exceptions for flow control.</p><p>That’s how I understand exceptions.</p><p>According to this paradigm, I would say we must:</p><ul> <li>Always use checked exceptions.</li> <li>Never throw/use unchecked exceptions.</li> <li>Use only Exception, without any sub-types.</li> <li>Always declare one exception type in the throws block.</li> <li>Never catch without rethrowing; read more about that here.</li></ul><p>This paradigm diverges from many other articles I’ve found on this subject. Let’s compare and discuss.</p><h2 id="runtime-vs-api-exceptions">Runtime vs. API Exceptions</h2><p>Oracle says some exceptions should be part of API (checked ones) while some are runtime exceptions and should not be part of it (unchecked). They will be documented in JavaDoc but not in the method signature.</p><p>I don’t understand the logic here, and I’m sure Java designers don’t understand it either. How and why are some exceptions important while others are not? Why do some of them deserve a proper API position in the throws block of the method signature while others don’t? What is the criteria?</p><p>I have an answer here, though. By introducing checked and unchecked exceptions, Java developers tried to solve the problem of methods that are too complex and messy. When a method is too big and does too many things at the same time (violates the single responsibility principle), it’s definitely better to let us keep some exceptions “hidden” (a.k.a. unchecked). But it’s not a real solution. It is only a temporary patch that does all of us more harm than good—methods keep growing in size and complexity.</p><p>Unchecked exceptions are a mistake in Java design, not checked ones.</p><p>Hiding the fact that a method may fail at some point is a mistake. That’s exactly what unchecked exceptions do.</p><p>Instead, we should make this fact visible. When a method does too many things, there will be too many points of failure, and the author of the method will realize that something is wrong—a method should not throw exceptions in so many situations. This will lead to refactoring. The existence of unchecked exceptions leads to a mess. By the way, checked exceptions don’t exist at all in Ruby, C#, Python, PHP, etc. This means that creators of these languages understand OOP even less than Java authors.</p><h2 id="checked-exceptions-are-too-noisy">Checked Exceptions Are Too Noisy</h2><p>Another common argument against checked exceptions is that they make our code more verbose. We have to put try/catch everywhere instead of staying focused on the main logic. Bozhidar Bozhanov even suggests a technical solution for this verbosity problem.</p><p>Again, I don’t understand this logic. If I want to do something when method save() fails, I catch the exception and handle the situation somehow. If I don’t want to do that, I just say my method also throws and pay no attention to exception handling. What is the problem? Where is the verbosity coming from?</p><p>I have an answer here, too. It’s coming from the existence of unchecked exceptions. We simply can’t always ignore failure, because the interfaces we’re using don’t allow us to do this. That’s all. For example, class Runnable, which is widely used for multi-thread programming, has method run() that is not supposed to throw anything. That’s why we always have to catch everything inside the method and rethrow checked exceptions as unchecked.</p><p>If all methods in all Java interfaces would be declared either as “safe” (throws nothing) or “unsafe” (throws Exception), everything would become logical and clear. If you want to stay “safe,” take responsibility for failure handling. Otherwise, be “unsafe” and let your users worry about safety.</p><p>No noise, very clean code, and obvious logic.</p><h2 id="inappropriately-exposed-implementation-details">Inappropriately Exposed Implementation Details</h2><p>Some say the ability to put a checked exception into throws in the method signature instead of catching it here and rethrowing a new type encourages us to have too many irrelevant exception types in method signatures. For example, our method save() may declare that it may throw OutOfMemoryException, even though it seems to have nothing to do with memory allocation. But it does allocate some memory, right? So such a memory overflow may happen during a file saving operation.</p><p>Yet again, I don’t get the logic of this argument. If all exceptions are checked, and we don’t have multiple exception types, we just throw Exception everywhere, and that’s it. Why do we need to care about the exception type in the first place? If we don’t use exceptions to control flow, we won’t do this.</p><p>If we really want to make our application memory overflow-resistant, we will introduce some memory manager, which will have something like the bigEnough() method, which will tell us whether our heap is big enough for the next operation. Using exceptions in such situations is a totally inappropriate approach to exception management in OOP.</p><h2 id="recoverable-exceptions">Recoverable Exceptions</h2><p>Joshua Bloch, in Effective Java, says to “use checked exceptions for recoverable conditions and runtime exceptions for programming errors.” He means something like this:</p>
<pre>try { save(file, data); } catch (Exception ex) { // We can't save the file, but it's OK // Let's move on and do something else }</pre>
<p>How is that any different from a famous anti-pattern called Don’t Use Exceptions for Flow Control? Joshua, with all due respect, you’re wrong. There are no such things as recoverable conditions in OOP. An exception indicates that the execution of a chain of calls from method to method is broken, and it’s time to go up through the chain and stop somewhere. But we never go back again after the exception:</p>
<pre>App#run() Data#update() Data#write() File#save() <-- Boom, there's a failure here, so we go up</pre>
<p>We can start this chain again, but we don’t go back after throw. In other words, we don’t do anything in the catch block. We only report the problem and wrap up execution. We never “recover!”</p><hr /><p>All arguments against checked exceptions demonstrate nothing but a serious misunderstanding of object-oriented programming by their authors. The mistake in Java and in many other languages is the existence of unchecked exceptions, not checked ones.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Do we need checked exceptions at all? The debate is over, isn’t it? Not for me. While most object-oriented languages don’t have them, and most programmers think checked exceptions are a Java mistake, I believe in the opposite—unchecked exceptions are the mistake. Moreover, I believe multiple exception types are a bad idea too.</p>
True Romance (1993) by Tony Scott<figcaption id="443dfa82">True Romance (1993) by Tony Scott</figcaption>
<p>Let me first explain how I understand exceptions in object-oriented programming. Then I’ll compare my understanding with a “traditional” approach, and we’ll discuss the differences. So, my understanding first.</p><p>Say there is a method that saves some binary data to a file:</p>
<pre>public void save(File file, byte[] data) throws Exception { // save data to the file }</pre>
<p>When everything goes right, the method just saves the data and returns control. When something is wrong, it throws Exception and we have to do something about it:</p>
<pre>try { save(file, data); } catch (Exception ex) { System.out.println("Sorry, we can't save right now."); }</pre>
<p>When a method says it throws an exception, I understand that the method is not safe. It may fail sometimes, and it’s my responsibility to either 1) handle this failure or 2) declare myself as unsafe too.</p><p>I know each method is designed with a single responsibility principle in mind. This is a guarantee to me that if method save() fails, it means the entire saving operation can’t be completed. If I need to know what the cause of this failure was, I will un-chain the exception—traverse the stack of chained exceptions and stack traces encapsulated in ex.</p><p>I never use exceptions for flow control, which means I never recover situations where exceptions are thrown. When an exception occurs, I let it float up to the highest level of the application. Sometimes I rethrow it in order to add more semantic information to the chain. That’s why it doesn’t matter to me what the cause of the exception thrown by save() was. I just know the method failed. That’s enough for me. Always.</p><p>For the same reason, I don’t need to differentiate between different exception types. I just don’t need that type of hierarchy. Exception is enough for me. Again, that’s because I don’t use exceptions for flow control.</p><p>That’s how I understand exceptions.</p><p>According to this paradigm, I would say we must:</p><ul> <li>Always use checked exceptions.</li> <li>Never throw/use unchecked exceptions.</li> <li>Use only Exception, without any sub-types.</li> <li>Always declare one exception type in the throws block.</li> <li>Never catch without rethrowing; read more about that here.</li></ul><p>This paradigm diverges from many other articles I’ve found on this subject. Let’s compare and discuss.</p><h2 id="runtime-vs-api-exceptions">Runtime vs. API Exceptions</h2><p>Oracle says some exceptions should be part of API (checked ones) while some are runtime exceptions and should not be part of it (unchecked). They will be documented in JavaDoc but not in the method signature.</p><p>I don’t understand the logic here, and I’m sure Java designers don’t understand it either. How and why are some exceptions important while others are not? Why do some of them deserve a proper API position in the throws block of the method signature while others don’t? What is the criteria?</p><p>I have an answer here, though. By introducing checked and unchecked exceptions, Java developers tried to solve the problem of methods that are too complex and messy. When a method is too big and does too many things at the same time (violates the single responsibility principle), it’s definitely better to let us keep some exceptions “hidden” (a.k.a. unchecked). But it’s not a real solution. It is only a temporary patch that does all of us more harm than good—methods keep growing in size and complexity.</p><p>Unchecked exceptions are a mistake in Java design, not checked ones.</p><p>Hiding the fact that a method may fail at some point is a mistake. That’s exactly what unchecked exceptions do.</p><p>Instead, we should make this fact visible. When a method does too many things, there will be too many points of failure, and the author of the method will realize that something is wrong—a method should not throw exceptions in so many situations. This will lead to refactoring. The existence of unchecked exceptions leads to a mess. By the way, checked exceptions don’t exist at all in Ruby, C#, Python, PHP, etc. This means that creators of these languages understand OOP even less than Java authors.</p><h2 id="checked-exceptions-are-too-noisy">Checked Exceptions Are Too Noisy</h2><p>Another common argument against checked exceptions is that they make our code more verbose. We have to put try/catch everywhere instead of staying focused on the main logic. Bozhidar Bozhanov even suggests a technical solution for this verbosity problem.</p><p>Again, I don’t understand this logic. If I want to do something when method save() fails, I catch the exception and handle the situation somehow. If I don’t want to do that, I just say my method also throws and pay no attention to exception handling. What is the problem? Where is the verbosity coming from?</p><p>I have an answer here, too. It’s coming from the existence of unchecked exceptions. We simply can’t always ignore failure, because the interfaces we’re using don’t allow us to do this. That’s all. For example, class Runnable, which is widely used for multi-thread programming, has method run() that is not supposed to throw anything. That’s why we always have to catch everything inside the method and rethrow checked exceptions as unchecked.</p><p>If all methods in all Java interfaces would be declared either as “safe” (throws nothing) or “unsafe” (throws Exception), everything would become logical and clear. If you want to stay “safe,” take responsibility for failure handling. Otherwise, be “unsafe” and let your users worry about safety.</p><p>No noise, very clean code, and obvious logic.</p><h2 id="inappropriately-exposed-implementation-details">Inappropriately Exposed Implementation Details</h2><p>Some say the ability to put a checked exception into throws in the method signature instead of catching it here and rethrowing a new type encourages us to have too many irrelevant exception types in method signatures. For example, our method save() may declare that it may throw OutOfMemoryException, even though it seems to have nothing to do with memory allocation. But it does allocate some memory, right? So such a memory overflow may happen during a file saving operation.</p><p>Yet again, I don’t get the logic of this argument. If all exceptions are checked, and we don’t have multiple exception types, we just throw Exception everywhere, and that’s it. Why do we need to care about the exception type in the first place? If we don’t use exceptions to control flow, we won’t do this.</p><p>If we really want to make our application memory overflow-resistant, we will introduce some memory manager, which will have something like the bigEnough() method, which will tell us whether our heap is big enough for the next operation. Using exceptions in such situations is a totally inappropriate approach to exception management in OOP.</p><h2 id="recoverable-exceptions">Recoverable Exceptions</h2><p>Joshua Bloch, in Effective Java, says to “use checked exceptions for recoverable conditions and runtime exceptions for programming errors.” He means something like this:</p>
<pre>try { save(file, data); } catch (Exception ex) { // We can't save the file, but it's OK // Let's move on and do something else }</pre>
<p>How is that any different from a famous anti-pattern called Don’t Use Exceptions for Flow Control? Joshua, with all due respect, you’re wrong. There are no such things as recoverable conditions in OOP. An exception indicates that the execution of a chain of calls from method to method is broken, and it’s time to go up through the chain and stop somewhere. But we never go back again after the exception:</p>
<pre>App#run() Data#update() Data#write() File#save() <-- Boom, there's a failure here, so we go up</pre>
<p>We can start this chain again, but we don’t go back after throw. In other words, we don’t do anything in the catch block. We only report the problem and wrap up execution. We never “recover!”</p><hr /><p>All arguments against checked exceptions demonstrate nothing but a serious misunderstanding of object-oriented programming by their authors. The mistake in Java and in many other languages is the existence of unchecked exceptions, not checked ones.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Fools Don't Write Unit Tests </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/07/16/fools-dont-write-unit-tests.html>12 Best</li> <li /2015/07/16/fools-dont-write-unit-tests.html>All 292</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Webinars</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Talks</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Books</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Papers</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Pets</li> <li /2015/07/16/fools-dont-write-unit-tests.html class=”highlighted”>Trainings</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Award</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Testimonials</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Shift-M</li> <li /2015/07/16/fools-dont-write-unit-tests.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Fools Don’t Write Unit Tests</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Palo Alto, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>“We don’t have time to write unit tests” or “We don’t have the budget for unit testing” are complaints I hear very often. Sometimes it may sound like, “We don’t use TDD, so that’s why there are no unit tests,” or even “TDD is too expensive for us now.” I’m sure you’ve heard this or even said it yourself. It doesn’t make any sense to me. I don’t get the logic. In my understanding, unit testing is not a product; it’s a tool. You use tests to develop a product faster and better. How can you say you don’t have time to use the tool that makes your work faster? Let me show you how.</p>
Ex Machina (2015) by Alex Garland<figcaption id="2b57602a">Ex Machina (2015) by Alex Garland</figcaption>
<p>TDD or not, a unit test is a unit test. Either you create it before the main piece of code or after it.</p><p>A unit test is a tool that helps you, a developer of software, “run” your stuff and see how it works. How else can you check if it works? When I hear, “I don’t have time for unit tests,” my next question is: “How did you test your code?”</p><p>I seriously can’t understand how it is possible to write something and then not test it. Well, unless you’re paid monthly and nobody really cares about your deliverables. If you do care about the software you produce, you’re interested in seeing it in action, right?</p><p>So, how do you do this?</p><p>If it’s a one-page PHP website, you can probably run it locally on Apache, modify it on disk, and then Cmd+R many times. That will work for a primitive piece of code and only for you, a single developer of it. But I hear this “I don’t have time” argument from programmers working on enterprise systems. How do you guys test your code?</p><aside class="quote">Not because you didn’t have time, you just didn’t know how</aside><p>I would compare unit tests with OOP classes. You can design the entire application in a single class with a few thousand methods. You will save time on creating other classes, structuring them, thinking about connections between them, etc. It will be a single 20,000-line .java file. And you’ll say that “you didn’t have time to create classes,” right? What would we say about such a product and the author of it? Right, we’d say he or she is just stupid. And it has nothing to do with time or budget. Such a programmer just doesn’t know how to use object-oriented programming tools, like encapsulation, inheritance, polymorphism, interfaces, method overloading, etc. It’s not about time or budget; it’s about skills and discipline.</p><p>The same is true for unit tests. If you create code without unit tests, it may work, just like that monster class with 20,000 lines, but the quality of your product will be very low. And not because you didn’t have time to write unit tests, but because you didn’t know how to do it.</p><p>So every time I hear, “I didn’t have time for unit testing,” I understand that you just didn’t know how and are trying to conceal that fact behind false excuses. It’s not professional, to say the least.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>“We don’t have time to write unit tests” or “We don’t have the budget for unit testing” are complaints I hear very often. Sometimes it may sound like, “We don’t use TDD, so that’s why there are no unit tests,” or even “TDD is too expensive for us now.” I’m sure you’ve heard this or even said it yourself. It doesn’t make any sense to me. I don’t get the logic. In my understanding, unit testing is not a product; it’s a tool. You use tests to develop a product faster and better. How can you say you don’t have time to use the tool that makes your work faster? Let me show you how.</p>
Ex Machina (2015) by Alex Garland<figcaption id="2b57602a">Ex Machina (2015) by Alex Garland</figcaption>
<p>TDD or not, a unit test is a unit test. Either you create it before the main piece of code or after it.</p><p>A unit test is a tool that helps you, a developer of software, “run” your stuff and see how it works. How else can you check if it works? When I hear, “I don’t have time for unit tests,” my next question is: “How did you test your code?”</p><p>I seriously can’t understand how it is possible to write something and then not test it. Well, unless you’re paid monthly and nobody really cares about your deliverables. If you do care about the software you produce, you’re interested in seeing it in action, right?</p><p>So, how do you do this?</p><p>If it’s a one-page PHP website, you can probably run it locally on Apache, modify it on disk, and then Cmd+R many times. That will work for a primitive piece of code and only for you, a single developer of it. But I hear this “I don’t have time” argument from programmers working on enterprise systems. How do you guys test your code?</p><aside class="quote">Not because you didn’t have time, you just didn’t know how</aside><p>I would compare unit tests with OOP classes. You can design the entire application in a single class with a few thousand methods. You will save time on creating other classes, structuring them, thinking about connections between them, etc. It will be a single 20,000-line .java file. And you’ll say that “you didn’t have time to create classes,” right? What would we say about such a product and the author of it? Right, we’d say he or she is just stupid. And it has nothing to do with time or budget. Such a programmer just doesn’t know how to use object-oriented programming tools, like encapsulation, inheritance, polymorphism, interfaces, method overloading, etc. It’s not about time or budget; it’s about skills and discipline.</p><p>The same is true for unit tests. If you create code without unit tests, it may work, just like that monster class with 20,000 lines, but the quality of your product will be very low. And not because you didn’t have time to write unit tests, but because you didn’t know how to do it.</p><p>So every time I hear, “I didn’t have time for unit testing,” I understand that you just didn’t know how and are trying to conceal that fact behind false excuses. It’s not professional, to say the least.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> A Few Valid Reasons to Reject a Bug Fix </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>12 Best</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>All 292</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Webinars</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Talks</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Books</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Papers</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Pets</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html class=”highlighted”>Trainings</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Award</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Testimonials</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Shift-M</li> <li /2015/06/22/valid-reasons-to-reject-bug-fix.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">A Few Valid Reasons to Reject a Bug Fix</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>A bug exists when something doesn’t work as expected. A bug fix is basically a patch (a pull request) to the existing code base that is supposed to solve the problem and make sure that “something” works as expected. Very often, such a patch fixes one thing and breaks many others. I believe that sometimes it’s necessary to reject a bug fix and ask its author to re-do the patch in order to protect the project from bigger problems. There are a few valid reasons for such a rejection, according to my experience.</p>
El Crimen Perfecto (2004) by Álex de la Iglesia<figcaption id="3827b7b3">El Crimen Perfecto (2004) by Álex de la Iglesia</figcaption>
<h2 id="it-degrades-code-coverage">It Degrades Code Coverage</h2><p>This is a very common situation: After the changes are made in one place, unit tests fail in some other place. The bug is fixed, but some possibly unrelated unit tests start to report failure. Under pressure or simply because we’re lazy, we don’t fix them; we simply remove the tests or mark them as temporarily “skipped.” The problem is solved, the build is clean, so let’s merge the patch and call it a day, right? Wrong!</p><p>Even though I’m in favor of cutting corners as much as possible, this is the corner I don’t recommend you cut.</p><p>The unit tests are there precisely to prevent us from breaking the product when under pressure.</p><p>Obviously, there are situations when the unit tests are wrong and we have to delete them. In those cases, don’t forget to create new ones.</p>
badge
<p>There are also situations when the bug must be fixed in a few minutes to put the system back online and fixing all unit tests will take an hour. Such a situation is a strong indicator that you’ve got a terrible underlying situation with test coverage in the product. There’s no doubt that we have to make a fix and ask our tests to shut up for some time. But in this case, make sure the next task your team is working on after the bug fix is released is correcting those disabled unit tests. I would recommend reading Working Effectively With Legacy Code by Michael Feathers, which tackles this very subject.</p><h2 id="it-doesnt-reproduce-the-issue">It Doesn’t Reproduce the Issue</h2><p>Sometimes the entire system may be down simply because of a small typo in one line of code. An obvious bug fix is to remove the typo, but that’s not what a good project is expecting from us if we care about its quality. The problem is not the typo but rather the absence of unit tests that would catch the typo at the deployment phase.</p><aside class="quote">The problem is not the typo but rather the absence of unit tests that would catch the typo at the deployment phase</aside><p>The real problem is the lack of test code coverage in this particular section of the code. By removing the typo, we’re not helping the project in any way. Moreover, we’re doing it a disservice—we’re concealing the real problem.</p><p>Thus, no matter how small or cosmetic the issue is, its bug fix must contain an extra test that first reproduces the bug. Without such a test, a bug fix is a waste of the project’s money.</p><p>Furthermore, without a unit test reproducing the issue, there is no guarantee that our bug fix doesn’t introduce more bugs. I would even say that the more bug fixes we have, the higher the entropy. And the only way to decrease this uncertainty is by covering the code with unit tests. Without a test, a bug fix brings more disorder to the code base.</p><h2 id="it-is-too-big">It Is Too Big</h2><p>Bug fixes are not features; they must be small and focused. It’s a very typical mistake for programmers to get carried away while fixing a bug and introduce some refactoring together with a fix. The result is that the patch gets rather big and difficult to understand. I’m not against refactoring; it’s a very important and positive thing for a project, but do it separately after the bug is fixed and merged.</p><p>No refactoring while fixing a bug!</p><p>Create a new unit test, reproduce the bug, and commit it. Fix the bug in the existing code base, no matter how ugly it is. Create new bugs, asking the team to improve the situation with the ugly code base. If interested, assign those bugs to yourself. Or maybe somebody else will be interested in fixing them and refactoring the code. But all that will happen later in other pull requests with new code reviews and new merges.</p><p>It’s not about being lazy and unwilling to fix what looks bad. It’s about a discipline, which is much more important than good intentions.</p><h2 id="it-solves-more-than-one-issue">It Solves More Than One Issue</h2><p>Always fix one issue at a time—simple as that. No exceptions. When a bug fix patch contains code changes that fix multiple issues, it is very difficult to understand which issue is tested, which one is reproduced, and how they relate to each other. Combining several bug fixes into a single pull request is a very bad practice.</p><p>No matter how simple the fix is, keep it separate from others. Review, test, and merge it individually. This will also increase the traceability of changes. It will always be easy to understand who made that fix, who reviewed the code, and when it was merged (and deployed).</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>A bug exists when something doesn’t work as expected. A bug fix is basically a patch (a pull request) to the existing code base that is supposed to solve the problem and make sure that “something” works as expected. Very often, such a patch fixes one thing and breaks many others. I believe that sometimes it’s necessary to reject a bug fix and ask its author to re-do the patch in order to protect the project from bigger problems. There are a few valid reasons for such a rejection, according to my experience.</p>
El Crimen Perfecto (2004) by Álex de la Iglesia<figcaption id="3827b7b3">El Crimen Perfecto (2004) by Álex de la Iglesia</figcaption>
<h2 id="it-degrades-code-coverage">It Degrades Code Coverage</h2><p>This is a very common situation: After the changes are made in one place, unit tests fail in some other place. The bug is fixed, but some possibly unrelated unit tests start to report failure. Under pressure or simply because we’re lazy, we don’t fix them; we simply remove the tests or mark them as temporarily “skipped.” The problem is solved, the build is clean, so let’s merge the patch and call it a day, right? Wrong!</p><p>Even though I’m in favor of cutting corners as much as possible, this is the corner I don’t recommend you cut.</p><p>The unit tests are there precisely to prevent us from breaking the product when under pressure.</p><p>Obviously, there are situations when the unit tests are wrong and we have to delete them. In those cases, don’t forget to create new ones.</p>
badge
<p>There are also situations when the bug must be fixed in a few minutes to put the system back online and fixing all unit tests will take an hour. Such a situation is a strong indicator that you’ve got a terrible underlying situation with test coverage in the product. There’s no doubt that we have to make a fix and ask our tests to shut up for some time. But in this case, make sure the next task your team is working on after the bug fix is released is correcting those disabled unit tests. I would recommend reading Working Effectively With Legacy Code by Michael Feathers, which tackles this very subject.</p><h2 id="it-doesnt-reproduce-the-issue">It Doesn’t Reproduce the Issue</h2><p>Sometimes the entire system may be down simply because of a small typo in one line of code. An obvious bug fix is to remove the typo, but that’s not what a good project is expecting from us if we care about its quality. The problem is not the typo but rather the absence of unit tests that would catch the typo at the deployment phase.</p><aside class="quote">The problem is not the typo but rather the absence of unit tests that would catch the typo at the deployment phase</aside><p>The real problem is the lack of test code coverage in this particular section of the code. By removing the typo, we’re not helping the project in any way. Moreover, we’re doing it a disservice—we’re concealing the real problem.</p><p>Thus, no matter how small or cosmetic the issue is, its bug fix must contain an extra test that first reproduces the bug. Without such a test, a bug fix is a waste of the project’s money.</p><p>Furthermore, without a unit test reproducing the issue, there is no guarantee that our bug fix doesn’t introduce more bugs. I would even say that the more bug fixes we have, the higher the entropy. And the only way to decrease this uncertainty is by covering the code with unit tests. Without a test, a bug fix brings more disorder to the code base.</p><h2 id="it-is-too-big">It Is Too Big</h2><p>Bug fixes are not features; they must be small and focused. It’s a very typical mistake for programmers to get carried away while fixing a bug and introduce some refactoring together with a fix. The result is that the patch gets rather big and difficult to understand. I’m not against refactoring; it’s a very important and positive thing for a project, but do it separately after the bug is fixed and merged.</p><p>No refactoring while fixing a bug!</p><p>Create a new unit test, reproduce the bug, and commit it. Fix the bug in the existing code base, no matter how ugly it is. Create new bugs, asking the team to improve the situation with the ugly code base. If interested, assign those bugs to yourself. Or maybe somebody else will be interested in fixing them and refactoring the code. But all that will happen later in other pull requests with new code reviews and new merges.</p><p>It’s not about being lazy and unwilling to fix what looks bad. It’s about a discipline, which is much more important than good intentions.</p><h2 id="it-solves-more-than-one-issue">It Solves More Than One Issue</h2><p>Always fix one issue at a time—simple as that. No exceptions. When a bug fix patch contains code changes that fix multiple issues, it is very difficult to understand which issue is tested, which one is reproduced, and how they relate to each other. Combining several bug fixes into a single pull request is a very bad practice.</p><p>No matter how simple the fix is, keep it separate from others. Review, test, and merge it individually. This will also increase the traceability of changes. It will always be easy to understand who made that fix, who reviewed the code, and when it was merged (and deployed).</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Good Programmers Write Bug-Free Code, Don't They? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/06/18/good-programmers-bug-free.html>12 Best</li> <li /2015/06/18/good-programmers-bug-free.html>All 292</li> <li /2015/06/18/good-programmers-bug-free.html>Webinars</li> <li /2015/06/18/good-programmers-bug-free.html>Talks</li> <li /2015/06/18/good-programmers-bug-free.html>Books</li> <li /2015/06/18/good-programmers-bug-free.html>Papers</li> <li /2015/06/18/good-programmers-bug-free.html>Pets</li> <li /2015/06/18/good-programmers-bug-free.html class=”highlighted”>Trainings</li> <li /2015/06/18/good-programmers-bug-free.html>Award</li> <li /2015/06/18/good-programmers-bug-free.html>Testimonials</li> <li /2015/06/18/good-programmers-bug-free.html>Shift-M</li> <li /2015/06/18/good-programmers-bug-free.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Good Programmers Write Bug-Free Code, Don’t They?</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>Good programmers create fewer bugs while bad programmers cause more. Sounds logical, doesn’t it? However, there is a lot of criticism of this way of thinking. Take this one, for example: Bugs are inevitable, and instead of expecting fewer bugs from us, let us focus on the right design and let testers find and report bugs; then we’ll fix them. Or this one: Being afraid to make a mistake makes me write slower and experiment less, which translates into lower-quality software. Read more about that here and here. But allow me to look at this from a different perspective and assert that yes, indeed, good programmers create fewer bugs.</p>
Sabotage! (2000) by Esteban and Jose Miguel Ibarretxe<figcaption id="8a4f6549">Sabotage! (2000) by Esteban and Jose Miguel Ibarretxe</figcaption>
<p>I think this is all about how we define quality and what a bug is.</p><p>If we look at a traditional and very “intuitive” definition of a bug, it is something that causes our software to produce an incorrect or unexpected result. However, if we think more about how the software is actually used and by whom, we’ll see that there are many other types of bugs, including scalability, reliability, and even maintainability ones.</p><p>If we put all those “-ilities” in a list and prioritize them by their severity and importance to the business, we’ll see that functionality-related bugs are rather far from the top. I would actually put maintainability at the top.</p><p>My point is that mistakes are not all equal. If I’m writing a PDF report generated by a piece of Java code and my report misses the footer, that’s one type of bug, and its fix will cost the business X dollars. On the other hand, if my PDF generation code is so difficult to modify that in order to change its format from A4 to US Letter we have to rewrite it from scratch, that’s a completely different type of bug. Needless to say, its fixing will be many times more expensive.</p><aside class="quote">Good programmers make cheaper mistakes in order to avoid making more expensive ones.</aside><p>So yes, mistakes are inevitable. We should not be afraid of them and be ready to make them. However, good programmers make cheaper mistakes in order to avoid making more expensive ones.</p><p>Good programmers understand that in the limited amount of time we usually have to implement the software, we have to sacrifice functionality in order to gain maintainability. Ideally, you want to achieve both, but in reality, it’s next to impossible.</p><p>We all work under pressure, and we have time and money constraints. Within these constraints, good programmers prefer to make functionality buggy and incomplete while keeping the design clean and easy to maintain. There are exceptions, of course, where the business prioritizes functionality above everything else, but such situations happen very rarely (if the business is smart).</p><p>To summarize, I think that a good programmer makes more functional bugs than a bad programmer, though the bugs made by a bad programmer are more expensive than bugs made by a good programmer.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Good programmers create fewer bugs while bad programmers cause more. Sounds logical, doesn’t it? However, there is a lot of criticism of this way of thinking. Take this one, for example: Bugs are inevitable, and instead of expecting fewer bugs from us, let us focus on the right design and let testers find and report bugs; then we’ll fix them. Or this one: Being afraid to make a mistake makes me write slower and experiment less, which translates into lower-quality software. Read more about that here and here. But allow me to look at this from a different perspective and assert that yes, indeed, good programmers create fewer bugs.</p>
Sabotage! (2000) by Esteban and Jose Miguel Ibarretxe<figcaption id="8a4f6549">Sabotage! (2000) by Esteban and Jose Miguel Ibarretxe</figcaption>
<p>I think this is all about how we define quality and what a bug is.</p><p>If we look at a traditional and very “intuitive” definition of a bug, it is something that causes our software to produce an incorrect or unexpected result. However, if we think more about how the software is actually used and by whom, we’ll see that there are many other types of bugs, including scalability, reliability, and even maintainability ones.</p><p>If we put all those “-ilities” in a list and prioritize them by their severity and importance to the business, we’ll see that functionality-related bugs are rather far from the top. I would actually put maintainability at the top.</p><p>My point is that mistakes are not all equal. If I’m writing a PDF report generated by a piece of Java code and my report misses the footer, that’s one type of bug, and its fix will cost the business X dollars. On the other hand, if my PDF generation code is so difficult to modify that in order to change its format from A4 to US Letter we have to rewrite it from scratch, that’s a completely different type of bug. Needless to say, its fixing will be many times more expensive.</p><aside class="quote">Good programmers make cheaper mistakes in order to avoid making more expensive ones.</aside><p>So yes, mistakes are inevitable. We should not be afraid of them and be ready to make them. However, good programmers make cheaper mistakes in order to avoid making more expensive ones.</p><p>Good programmers understand that in the limited amount of time we usually have to implement the software, we have to sacrifice functionality in order to gain maintainability. Ideally, you want to achieve both, but in reality, it’s next to impossible.</p><p>We all work under pressure, and we have time and money constraints. Within these constraints, good programmers prefer to make functionality buggy and incomplete while keeping the design clean and easy to maintain. There are exceptions, of course, where the business prioritizes functionality above everything else, but such situations happen very rarely (if the business is smart).</p><p>To summarize, I think that a good programmer makes more functional bugs than a bad programmer, though the bugs made by a bad programmer are more expensive than bugs made by a good programmer.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Wikipedia's Definition of a Software Bug Is Wrong </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/06/11/wikipedia-bug-definition.html>12 Best</li> <li /2015/06/11/wikipedia-bug-definition.html>All 292</li> <li /2015/06/11/wikipedia-bug-definition.html>Webinars</li> <li /2015/06/11/wikipedia-bug-definition.html>Talks</li> <li /2015/06/11/wikipedia-bug-definition.html>Books</li> <li /2015/06/11/wikipedia-bug-definition.html>Papers</li> <li /2015/06/11/wikipedia-bug-definition.html>Pets</li> <li /2015/06/11/wikipedia-bug-definition.html class=”highlighted”>Trainings</li> <li /2015/06/11/wikipedia-bug-definition.html>Award</li> <li /2015/06/11/wikipedia-bug-definition.html>Testimonials</li> <li /2015/06/11/wikipedia-bug-definition.html>Shift-M</li> <li /2015/06/11/wikipedia-bug-definition.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Wikipedia’s Definition of a Software Bug Is Wrong</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Here is what Wikipedia says at the time of this writing:</p><blockquote><p>A software bug is an error, flaw, failure, or fault in a computer program or system that causes it to produce an incorrect or unexpected result or to behave in unintended ways.</p></blockquote><p>I think that’s incomplete. The definition entirely excludes “non-behavioral” defects related to, for example, maintainability and reusability.</p><p>As you know, every piece of software has functional and non-functional requirements. Functional requirements tell us what the software has to do, and non-functional requirements document how it has to do it. For example, here is a functional requirement:</p>
<pre>The user can generate a PDF report.</pre>
<p>If our software doesn’t generate a PDF report and crashes instead, that’s a functional bug. If instead of a PDF report, it generates an empty page or a plain text document, that’s a functional bug. If there is no “generate PDF report” button at all and the user simply can’t start the PDF generation process, that’s a functional bug.</p><p>Here is an example of a non-functional requirement:</p>
<pre>PDF report generation must take less than 100ms.</pre>
<p>If our software generates a perfectly correct PDF report but it takes a minute, that’s a non-functional bug.</p><p>So far so good, since the bug definition given by Wikipedia perfectly covers both of them—if they happen, they will cause our software “to produce an incorrect or unexpected result or to behave in an unintended way.” The emphasis here is on the words “produce” and “behave.” They presume the software is doing something and we’re observing its behavior.</p><p>However, that’s not all of it.</p><p>What about maintainability? I may have this kind of non-functional requirement:</p>
<pre>The source code of the PDF generator must be easy to maintain and extend for an average Java programmer.</pre>
<p>It’s a rather vague requirement, but you get the idea.</p><p>Maintainability and reusability are very critical non-functional components of any modern software program, especially taking into account a very high cost of labor in the market. Very often, it’s more important to make sure the software is maintainable than fast. If it’s maintainable and slow, we can find new programmers to improve the code. If it is fast but unmaintainable, we won’t be able to do anything with it later and will have to rewrite it from scratch if some new feature is required. Read more about this in Are You a Hacker or a Designer?.</p><p>The definition of a software bug given by Wikipedia doesn’t cover maintainability and reusability flaws at all. That makes for a common source of confusion—an inconsistent code style is not a bug (see the discussion under this post).</p><p>That is wrong.</p><p>An inconsistent code style is a software bug, as is incomplete documentation, lack of documentation, code that’s too complex, the lack of a coding style guide, etc.</p><p>I would rewrite the software bug definition paragraph in Wikipedia like this:</p><blockquote><p>A software bug is an error, flaw, failure, or fault in a computer program or system that causes it to violate at least one of its functional or non-functional requirements.</p></blockquote><p>This definition looks more accurate to me.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Here is what Wikipedia says at the time of this writing:</p><blockquote><p>A software bug is an error, flaw, failure, or fault in a computer program or system that causes it to produce an incorrect or unexpected result or to behave in unintended ways.</p></blockquote><p>I think that’s incomplete. The definition entirely excludes “non-behavioral” defects related to, for example, maintainability and reusability.</p><p>As you know, every piece of software has functional and non-functional requirements. Functional requirements tell us what the software has to do, and non-functional requirements document how it has to do it. For example, here is a functional requirement:</p>
<pre>The user can generate a PDF report.</pre>
<p>If our software doesn’t generate a PDF report and crashes instead, that’s a functional bug. If instead of a PDF report, it generates an empty page or a plain text document, that’s a functional bug. If there is no “generate PDF report” button at all and the user simply can’t start the PDF generation process, that’s a functional bug.</p><p>Here is an example of a non-functional requirement:</p>
<pre>PDF report generation must take less than 100ms.</pre>
<p>If our software generates a perfectly correct PDF report but it takes a minute, that’s a non-functional bug.</p><p>So far so good, since the bug definition given by Wikipedia perfectly covers both of them—if they happen, they will cause our software “to produce an incorrect or unexpected result or to behave in an unintended way.” The emphasis here is on the words “produce” and “behave.” They presume the software is doing something and we’re observing its behavior.</p><p>However, that’s not all of it.</p><p>What about maintainability? I may have this kind of non-functional requirement:</p>
<pre>The source code of the PDF generator must be easy to maintain and extend for an average Java programmer.</pre>
<p>It’s a rather vague requirement, but you get the idea.</p><p>Maintainability and reusability are very critical non-functional components of any modern software program, especially taking into account a very high cost of labor in the market. Very often, it’s more important to make sure the software is maintainable than fast. If it’s maintainable and slow, we can find new programmers to improve the code. If it is fast but unmaintainable, we won’t be able to do anything with it later and will have to rewrite it from scratch if some new feature is required. Read more about this in Are You a Hacker or a Designer?.</p><p>The definition of a software bug given by Wikipedia doesn’t cover maintainability and reusability flaws at all. That makes for a common source of confusion—an inconsistent code style is not a bug (see the discussion under this post).</p><p>That is wrong.</p><p>An inconsistent code style is a software bug, as is incomplete documentation, lack of documentation, code that’s too complex, the lack of a coding style guide, etc.</p><p>I would rewrite the software bug definition paragraph in Wikipedia like this:</p><blockquote><p>A software bug is an error, flaw, failure, or fault in a computer program or system that causes it to violate at least one of its functional or non-functional requirements.</p></blockquote><p>This definition looks more accurate to me.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> A Few Thoughts on Unit Test Scaffolding </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/05/25/unit-test-scaffolding.html>12 Best</li> <li /2015/05/25/unit-test-scaffolding.html>All 292</li> <li /2015/05/25/unit-test-scaffolding.html>Webinars</li> <li /2015/05/25/unit-test-scaffolding.html>Talks</li> <li /2015/05/25/unit-test-scaffolding.html>Books</li> <li /2015/05/25/unit-test-scaffolding.html>Papers</li> <li /2015/05/25/unit-test-scaffolding.html>Pets</li> <li /2015/05/25/unit-test-scaffolding.html class=”highlighted”>Trainings</li> <li /2015/05/25/unit-test-scaffolding.html>Award</li> <li /2015/05/25/unit-test-scaffolding.html>Testimonials</li> <li /2015/05/25/unit-test-scaffolding.html>Shift-M</li> <li /2015/05/25/unit-test-scaffolding.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">A Few Thoughts on Unit Test Scaffolding</h1><ul class="subline"> <li> </li> <li class="desktop-only" itemprop="locationCreated">Atherton, CA</li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>When I start to repeat myself in unit test methods by creating the same objects and preparing the data to run the test, I feel disappointed in my design. Long test methods with a lot of code duplication just don’t look right. To simplify and shorten them, there are basically two options, at least in Java: 1) private properties initialized through @Before and @BeforeClass, and 2) private static methods. They both look anti-OOP to me, and I think there is an alternative. Let me explain.</p>
Léon: The Professional by Luc Besson<figcaption id="6f716aac">Léon: The Professional by Luc Besson</figcaption>
<p>JUnit officially suggests a test fixture:</p>
<pre>public final class MetricsTest { private File temp; private Folder folder; @Before public void prepare() { this.temp = Files.createTempDirectory("test"); this.folder = new DiscFolder(this.temp); this.folder.save("first.txt", "Hello, world!"); this.folder.save("second.txt", "Goodbye!"); } @After public void clean() { FileUtils.deleteDirectory(this.temp); } @Test public void calculatesTotalSize() { assertEquals(22, new Metrics(this.folder).size()); } @Test public void countsWordsInFiles() { assertEquals(4, new Metrics(this.folder).wc()); } }</pre>
<p>I think it’s obvious what this test is doing. First, in prepare(), it creates a “test fixture” of type Folder. That is used in all three tests as an argument for the Metrics constructor. The real class being tested here is Metrics while this.folder is something we need in order to test it.</p><aside class="youtube"> <div class="box"> YouTube video #l6MpCBzwDbg<div class="play"></div></div><div>What Fake Objects Are For? (webinar #8); 4 November 2015.</div></aside><p>What’s wrong with this test? There is one serious issue: coupling between test methods. Test methods (and all tests in general) must be perfectly isolated from each other. This means that changing one test must not affect any others. In this example, that is not the case. When I want to change the countsWords() test, I have to change the internals of before(), which will affect the other method in the test “class.”</p><p>With all due respect to JUnit, the idea of creating test fixtures in @Before and @After is wrong, mostly because it encourages developers to couple test methods.</p><p>Here is how we can improve our test and isolate test methods:</p>
<pre>public final class MetricsTest { @Test public void calculatesTotalSize() { final File dir = Files.createTempDirectory("test-1"); final Folder folder = MetricsTest.folder( dir, "first.txt:Hello, world!", "second.txt:Goodbye!" ); try { assertEquals(22, new Metrics(folder).size()); } finally { FileUtils.deleteDirectory(dir); } } @Test public void countsWordsInFiles() { final File dir = Files.createTempDirectory("test-2"); final Folder folder = MetricsTest.folder( dir, "alpha.txt:Three words here", "beta.txt:two words" "gamma.txt:one!" ); try { assertEquals(6, new Metrics(folder).wc()); } finally { FileUtils.deleteDirectory(dir); } } private static Folder folder(File dir, String... parts) { Folder folder = new DiscFolder(dir); for (final String part : parts) { final String[] pair = part.split(":", 2); this.folder.save(pair[0], pair[1]); } return folder; } }</pre>
<p>Does it look better now? We’re not there yet, but now our test methods are perfectly isolated. If I want to change one of them, I’m not going to affect the others because I pass all configuration parameters to a private static utility (!) method folder().</p><p>A utility method, huh? Yes, it smells.</p><p>The main issue with this design, even though it is way better than the previous one, is that it doesn’t prevent code duplication between test “classes.” If I need a similar test fixture of type Folder in another test case, I will have to move this static method there. Or even worse, I will have to create a utility class. Yes, there is nothing worse in object-oriented programming than utility classes.</p><p>A much better design would be to use “fake” objects instead of private static utilities. Here is how. First, we create a fake class and place it into src/main/java. This class can be used in tests and also in production code, if necessary (Fk for “fake”):</p>
<pre>public final class FkFolder implements Folder, Closeable { private final File dir; private final String[] parts; public FkFolder(String... prts) { this(Files.createTempDirectory("test-1"), parts); } public FkFolder(File file, String... prts) { this.dir = file; this.parts = parts; } @Override public Iterable<File> files() { final Folder folder = new DiscFolder(this.dir); for (final String part : this.parts) { final String[] pair = part.split(":", 2); folder.save(pair[0], pair[1]); } return folder.files(); } @Override public void close() { FileUtils.deleteDirectory(this.dir); } }</pre>
<p>Here is how our test will look now:</p>
<pre>public final class MetricsTest { @Test public void calculatesTotalSize() { final String[] parts = { "first.txt:Hello, world!", "second.txt:Goodbye!" }; try (final Folder folder = new FkFolder(parts)) { assertEquals(22, new Metrics(folder).size()); } } @Test public void countsWordsInFiles() { final String[] parts = { "alpha.txt:Three words here", "beta.txt:two words" "gamma.txt:one!" }; try (final Folder folder = new FkFolder(parts)) { assertEquals(6, new Metrics(folder).wc()); } } }</pre>
<p>What do you think? Isn’t it better than what JUnit offers? Isn’t it more reusable and extensible than utility methods?</p><p>To summarize, I believe scaffolding in unit testing must be done through fake objects that are shipped together with production code.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>When I start to repeat myself in unit test methods by creating the same objects and preparing the data to run the test, I feel disappointed in my design. Long test methods with a lot of code duplication just don’t look right. To simplify and shorten them, there are basically two options, at least in Java: 1) private properties initialized through @Before and @BeforeClass, and 2) private static methods. They both look anti-OOP to me, and I think there is an alternative. Let me explain.</p>
Léon: The Professional by Luc Besson<figcaption id="6f716aac">Léon: The Professional by Luc Besson</figcaption>
<p>JUnit officially suggests a test fixture:</p>
<pre>public final class MetricsTest { private File temp; private Folder folder; @Before public void prepare() { this.temp = Files.createTempDirectory("test"); this.folder = new DiscFolder(this.temp); this.folder.save("first.txt", "Hello, world!"); this.folder.save("second.txt", "Goodbye!"); } @After public void clean() { FileUtils.deleteDirectory(this.temp); } @Test public void calculatesTotalSize() { assertEquals(22, new Metrics(this.folder).size()); } @Test public void countsWordsInFiles() { assertEquals(4, new Metrics(this.folder).wc()); } }</pre>
<p>I think it’s obvious what this test is doing. First, in prepare(), it creates a “test fixture” of type Folder. That is used in all three tests as an argument for the Metrics constructor. The real class being tested here is Metrics while this.folder is something we need in order to test it.</p><aside class="youtube"> <div class="box"> YouTube video #l6MpCBzwDbg<div class="play"></div></div><div>What Fake Objects Are For? (webinar #8); 4 November 2015.</div></aside><p>What’s wrong with this test? There is one serious issue: coupling between test methods. Test methods (and all tests in general) must be perfectly isolated from each other. This means that changing one test must not affect any others. In this example, that is not the case. When I want to change the countsWords() test, I have to change the internals of before(), which will affect the other method in the test “class.”</p><p>With all due respect to JUnit, the idea of creating test fixtures in @Before and @After is wrong, mostly because it encourages developers to couple test methods.</p><p>Here is how we can improve our test and isolate test methods:</p>
<pre>public final class MetricsTest { @Test public void calculatesTotalSize() { final File dir = Files.createTempDirectory("test-1"); final Folder folder = MetricsTest.folder( dir, "first.txt:Hello, world!", "second.txt:Goodbye!" ); try { assertEquals(22, new Metrics(folder).size()); } finally { FileUtils.deleteDirectory(dir); } } @Test public void countsWordsInFiles() { final File dir = Files.createTempDirectory("test-2"); final Folder folder = MetricsTest.folder( dir, "alpha.txt:Three words here", "beta.txt:two words" "gamma.txt:one!" ); try { assertEquals(6, new Metrics(folder).wc()); } finally { FileUtils.deleteDirectory(dir); } } private static Folder folder(File dir, String... parts) { Folder folder = new DiscFolder(dir); for (final String part : parts) { final String[] pair = part.split(":", 2); this.folder.save(pair[0], pair[1]); } return folder; } }</pre>
<p>Does it look better now? We’re not there yet, but now our test methods are perfectly isolated. If I want to change one of them, I’m not going to affect the others because I pass all configuration parameters to a private static utility (!) method folder().</p><p>A utility method, huh? Yes, it smells.</p><p>The main issue with this design, even though it is way better than the previous one, is that it doesn’t prevent code duplication between test “classes.” If I need a similar test fixture of type Folder in another test case, I will have to move this static method there. Or even worse, I will have to create a utility class. Yes, there is nothing worse in object-oriented programming than utility classes.</p><p>A much better design would be to use “fake” objects instead of private static utilities. Here is how. First, we create a fake class and place it into src/main/java. This class can be used in tests and also in production code, if necessary (Fk for “fake”):</p>
<pre>public final class FkFolder implements Folder, Closeable { private final File dir; private final String[] parts; public FkFolder(String... prts) { this(Files.createTempDirectory("test-1"), parts); } public FkFolder(File file, String... prts) { this.dir = file; this.parts = parts; } @Override public Iterable<File> files() { final Folder folder = new DiscFolder(this.dir); for (final String part : this.parts) { final String[] pair = part.split(":", 2); folder.save(pair[0], pair[1]); } return folder.files(); } @Override public void close() { FileUtils.deleteDirectory(this.dir); } }</pre>
<p>Here is how our test will look now:</p>
<pre>public final class MetricsTest { @Test public void calculatesTotalSize() { final String[] parts = { "first.txt:Hello, world!", "second.txt:Goodbye!" }; try (final Folder folder = new FkFolder(parts)) { assertEquals(22, new Metrics(folder).size()); } } @Test public void countsWordsInFiles() { final String[] parts = { "alpha.txt:Three words here", "beta.txt:two words" "gamma.txt:one!" }; try (final Folder folder = new FkFolder(parts)) { assertEquals(6, new Metrics(folder).wc()); } } }</pre>
<p>What do you think? Isn’t it better than what JUnit offers? Isn’t it more reusable and extensible than utility methods?</p><p>To summarize, I believe scaffolding in unit testing must be done through fake objects that are shipped together with production code.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Constructors Must Be Code-Free </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/05/07/ctors-must-be-code-free.html>12 Best</li> <li /2015/05/07/ctors-must-be-code-free.html>All 292</li> <li /2015/05/07/ctors-must-be-code-free.html>Webinars</li> <li /2015/05/07/ctors-must-be-code-free.html>Talks</li> <li /2015/05/07/ctors-must-be-code-free.html>Books</li> <li /2015/05/07/ctors-must-be-code-free.html>Papers</li> <li /2015/05/07/ctors-must-be-code-free.html>Pets</li> <li /2015/05/07/ctors-must-be-code-free.html class=”highlighted”>Trainings</li> <li /2015/05/07/ctors-must-be-code-free.html>Award</li> <li /2015/05/07/ctors-must-be-code-free.html>Testimonials</li> <li /2015/05/07/ctors-must-be-code-free.html>Shift-M</li> <li /2015/05/07/ctors-must-be-code-free.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Constructors Must Be Code-Free</h1><aside class='book'>book coverRead more about this subject in Section 1.3
of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>How much work should be done within a constructor? It seems reasonable to do some computations inside a constructor and then encapsulate results. That way, when the results are required by object methods, we’ll have them ready. Sounds like a good approach? No, it’s not. It’s a bad idea for one reason: It prevents composition of objects and makes them un-extensible.</p>
Kill Bill: Vol. 2 (2004) by Quentin Tarantino<figcaption id="780fae47">Kill Bill: Vol. 2 (2004) by Quentin Tarantino</figcaption>
<p>Let’s say we’re making an interface that would represent a name of a person:</p>
<pre>interface Name { String first(); }</pre>
<p>Pretty easy, right? Now, let’s try to implement it:</p>
<pre>public final class EnglishName implements Name { private final String name; public EnglishName(final CharSequence text) { this.name = text.toString().split(" ", 2)[0]; } @Override public String first() { return this.name; } }</pre>
<p>What’s wrong with this? It’s faster, right? It splits the name into parts only once and encapsulates them. Then, no matter how many times we call the first() method, it will return the same value and won’t need to do the splitting again. However, this is flawed thinking! Let me show you the right way and explain:</p>
<pre>public final class EnglishName implements Name { private final CharSequence text; public EnglishName(final CharSequence txt) { this.text = txt; } @Override public String first() { return this.text.toString().split("", 2)[0]; } }</pre>
<p>This is the right design. I can see you smiling, so let me prove my point.</p><p>Before I start proving, though, let me ask you to read this article: Composable Decorators vs. Imperative Utility Methods. It explains the difference between a static method and composable decorators. The first snippet above is very close to an imperative utility method, even though it looks like an object. The second example is a true object.</p><aside class="youtube"> <div class="box"> YouTube video #9yjtsCK6Wdk<div class="play"></div></div><div>A Few Thoughts About Constructors in OOP (webinar #7); 7 October 2015.</div></aside><p>In the first example, we are abusing the new operator and turning it into a static method, which does all calculations for us right here and now. This is what imperative programming is about. In imperative programming, we do all calculations right now and return fully ready results. In declarative programming, we are instead trying to delay calculations for as long as possible.</p><p>Let’s try to use our EnglishName class:</p>
<pre>final Name name = new EnglishName( new NameInPostgreSQL(/*...*/) ); if (/* something goes wrong */) { throw new IllegalStateException( String.format( "Hi, %s, we can't proceed with your application", name.first() ) ); }</pre>
<p>In the first line of this snippet, we are just making an instance of an object and labeling it name. We don’t want to go to the database yet and fetch the full name from there, split it into parts, and encapsulate them inside name. We just want to create an instance of an object. Such a parsing behavior would be a side effect for us and, in this case, will slow down the application. As you see, we may only need name.first() if something goes wrong and we need to construct an exception object.</p><p>My point is that having any computations done inside a constructor is a bad practice and must be avoided because they are side effects and are not requested by the object owner.</p><p>What about performance during the re-use of name, you may ask. If we make an instance of EnglishName and then call name.first() five times, we’ll end up with five calls to the String.split() method.</p><p>To solve that, we create another class, a composable decorator, which will help us solve this “re-use” problem:</p>
<pre>public final class CachedName implements Name { private final Name origin; public CachedName(final Name name) { this.origin = name; } @Override @Cacheable(forever = true) public String first() { return this.origin.first(); } }</pre>
<p>I’m using the Cacheable annotation from jcabi-aspects, but you can use any other caching tools available in Java (or other languages), like Guava Cache:</p>
<pre>public final class CachedName implements Name { private final Cache<Long, String> cache = CacheBuilder.newBuilder().build(); private final Name origin; public CachedName(final Name name) { this.origin = name; } @Override public String first() { return this.cache.get( 1L, new Callable<String>() { @Override public String call() { return CachedName.this.origin.first(); } } ); } }</pre>
<p>But please don’t make CachedName mutable and lazily loaded—it’s an anti-pattern, which I’ve discussed before in Objects Should Be Immutable.</p><p>This is how our code will look now:</p>
<pre>final Name name = new CachedName( new EnglishName( new NameInPostgreSQL(/*...*/) ) );</pre>
<p>It’s a very primitive example, but I hope you get the idea.</p><p>In this design, we’re basically splitting the object into two parts. The first one knows how to get the first name from the English name. The second one knows how to cache the results of this calculation in memory. And now it’s my decision, as a user of these classes, how exactly to use them. I will decide whether I need caching or not. This is what object composition is all about.</p><p>Let me reiterate that the only allowed statement inside a constructor is an assignment. If you need to put something else there, start thinking about refactoring—your class definitely needs a redesign.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>How much work should be done within a constructor? It seems reasonable to do some computations inside a constructor and then encapsulate results. That way, when the results are required by object methods, we’ll have them ready. Sounds like a good approach? No, it’s not. It’s a bad idea for one reason: It prevents composition of objects and makes them un-extensible.</p>
Kill Bill: Vol. 2 (2004) by Quentin Tarantino<figcaption id="780fae47">Kill Bill: Vol. 2 (2004) by Quentin Tarantino</figcaption>
<p>Let’s say we’re making an interface that would represent a name of a person:</p>
<pre>interface Name { String first(); }</pre>
<p>Pretty easy, right? Now, let’s try to implement it:</p>
<pre>public final class EnglishName implements Name { private final String name; public EnglishName(final CharSequence text) { this.name = text.toString().split(" ", 2)[0]; } @Override public String first() { return this.name; } }</pre>
<p>What’s wrong with this? It’s faster, right? It splits the name into parts only once and encapsulates them. Then, no matter how many times we call the first() method, it will return the same value and won’t need to do the splitting again. However, this is flawed thinking! Let me show you the right way and explain:</p>
<pre>public final class EnglishName implements Name { private final CharSequence text; public EnglishName(final CharSequence txt) { this.text = txt; } @Override public String first() { return this.text.toString().split("", 2)[0]; } }</pre>
<p>This is the right design. I can see you smiling, so let me prove my point.</p><p>Before I start proving, though, let me ask you to read this article: Composable Decorators vs. Imperative Utility Methods. It explains the difference between a static method and composable decorators. The first snippet above is very close to an imperative utility method, even though it looks like an object. The second example is a true object.</p><aside class="youtube"> <div class="box"> YouTube video #9yjtsCK6Wdk<div class="play"></div></div><div>A Few Thoughts About Constructors in OOP (webinar #7); 7 October 2015.</div></aside><p>In the first example, we are abusing the new operator and turning it into a static method, which does all calculations for us right here and now. This is what imperative programming is about. In imperative programming, we do all calculations right now and return fully ready results. In declarative programming, we are instead trying to delay calculations for as long as possible.</p><p>Let’s try to use our EnglishName class:</p>
<pre>final Name name = new EnglishName( new NameInPostgreSQL(/*...*/) ); if (/* something goes wrong */) { throw new IllegalStateException( String.format( "Hi, %s, we can't proceed with your application", name.first() ) ); }</pre>
<p>In the first line of this snippet, we are just making an instance of an object and labeling it name. We don’t want to go to the database yet and fetch the full name from there, split it into parts, and encapsulate them inside name. We just want to create an instance of an object. Such a parsing behavior would be a side effect for us and, in this case, will slow down the application. As you see, we may only need name.first() if something goes wrong and we need to construct an exception object.</p><p>My point is that having any computations done inside a constructor is a bad practice and must be avoided because they are side effects and are not requested by the object owner.</p><p>What about performance during the re-use of name, you may ask. If we make an instance of EnglishName and then call name.first() five times, we’ll end up with five calls to the String.split() method.</p><p>To solve that, we create another class, a composable decorator, which will help us solve this “re-use” problem:</p>
<pre>public final class CachedName implements Name { private final Name origin; public CachedName(final Name name) { this.origin = name; } @Override @Cacheable(forever = true) public String first() { return this.origin.first(); } }</pre>
<p>I’m using the Cacheable annotation from jcabi-aspects, but you can use any other caching tools available in Java (or other languages), like Guava Cache:</p>
<pre>public final class CachedName implements Name { private final Cache<Long, String> cache = CacheBuilder.newBuilder().build(); private final Name origin; public CachedName(final Name name) { this.origin = name; } @Override public String first() { return this.cache.get( 1L, new Callable<String>() { @Override public String call() { return CachedName.this.origin.first(); } } ); } }</pre>
<p>But please don’t make CachedName mutable and lazily loaded—it’s an anti-pattern, which I’ve discussed before in Objects Should Be Immutable.</p><p>This is how our code will look now:</p>
<pre>final Name name = new CachedName( new EnglishName( new NameInPostgreSQL(/*...*/) ) );</pre>
<p>It’s a very primitive example, but I hope you get the idea.</p><p>In this design, we’re basically splitting the object into two parts. The first one knows how to get the first name from the English name. The second one knows how to cache the results of this calculation in memory. And now it’s my decision, as a user of these classes, how exactly to use them. I will decide whether I need caching or not. This is what object composition is all about.</p><p>Let me reiterate that the only allowed statement inside a constructor is an assignment. If you need to put something else there, start thinking about refactoring—your class definitely needs a redesign.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> How to Implement an Iterating Adapter </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/04/30/iterating-adapter.html>12 Best</li> <li /2015/04/30/iterating-adapter.html>All 292</li> <li /2015/04/30/iterating-adapter.html>Webinars</li> <li /2015/04/30/iterating-adapter.html>Talks</li> <li /2015/04/30/iterating-adapter.html>Books</li> <li /2015/04/30/iterating-adapter.html>Papers</li> <li /2015/04/30/iterating-adapter.html>Pets</li> <li /2015/04/30/iterating-adapter.html class=”highlighted”>Trainings</li> <li /2015/04/30/iterating-adapter.html>Award</li> <li /2015/04/30/iterating-adapter.html>Testimonials</li> <li /2015/04/30/iterating-adapter.html>Shift-M</li> <li /2015/04/30/iterating-adapter.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">How to Implement an Iterating Adapter</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Iterator is one of the fundamental Java interfaces, introduced in Java 1.2. It is supposed to be very simple; however, in my experience, many Java developers don’t understand how to implement a custom one, which should iterate a stream of data coming from some other source. In other words, it becomes an adapter of another source of data, in the form of an iterator. I hope this example will help.</p><p>Let’s say we have an object of this class:</p>
<pre>final class Data { byte[] read(); }</pre>
<p>When we call read(), it returns a new array of bytes that were retrieved from somewhere. If there is nothing to retrieve, the array will be empty. Now, we want to create an adapter that would consume the bytes and let us iterate them:</p>
<pre>final class FluentData implements Iterator<Byte> { boolean hasNext() { /* ... */ } Byte next() { /* ... */ } void remove() { /* ... */ } }</pre>
<p>Here is how it should look (it is not thread-safe!):</p>
<pre>final class FluentData implements Iterator<Byte> { private final Data data; private final Queue<Byte> buffer = new LinkedList<>(); public FluentData(final Data dat) { this.data = dat; } public boolean hasNext() { if (this.buffer.isEmpty()) { for (final byte item : this.data.read()) { this.buffer.add(item); } } return !this.buffer.isEmpty(); } public Byte next() { if (!this.hasNext()) { throw new NoSuchElementException("Nothing left"); } return this.buffer.poll(); } public void remove() { throw new UnsupportedOperationException("It is read-only"); } }</pre>
<p>There is no way to make it thread-safe because the iterating process is outside the scope of the iterator. Even if we declare our methods as synchronized, this won’t guarantee that two threads won’t conflict when they both call hasNext() and next(). So don’t bother with it and just document the iterator as not thread-safe, then let its users synchronize one level higher when necessary.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Iterator is one of the fundamental Java interfaces, introduced in Java 1.2. It is supposed to be very simple; however, in my experience, many Java developers don’t understand how to implement a custom one, which should iterate a stream of data coming from some other source. In other words, it becomes an adapter of another source of data, in the form of an iterator. I hope this example will help.</p><p>Let’s say we have an object of this class:</p>
<pre>final class Data { byte[] read(); }</pre>
<p>When we call read(), it returns a new array of bytes that were retrieved from somewhere. If there is nothing to retrieve, the array will be empty. Now, we want to create an adapter that would consume the bytes and let us iterate them:</p>
<pre>final class FluentData implements Iterator<Byte> { boolean hasNext() { /* ... */ } Byte next() { /* ... */ } void remove() { /* ... */ } }</pre>
<p>Here is how it should look (it is not thread-safe!):</p>
<pre>final class FluentData implements Iterator<Byte> { private final Data data; private final Queue<Byte> buffer = new LinkedList<>(); public FluentData(final Data dat) { this.data = dat; } public boolean hasNext() { if (this.buffer.isEmpty()) { for (final byte item : this.data.read()) { this.buffer.add(item); } } return !this.buffer.isEmpty(); } public Byte next() { if (!this.hasNext()) { throw new NoSuchElementException("Nothing left"); } return this.buffer.poll(); } public void remove() { throw new UnsupportedOperationException("It is read-only"); } }</pre>
<p>There is no way to make it thread-safe because the iterating process is outside the scope of the iterator. Even if we declare our methods as synchronized, this won’t guarantee that two threads won’t conflict when they both call hasNext() and next(). So don’t bother with it and just document the iterator as not thread-safe, then let its users synchronize one level higher when necessary.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Software Quality Award, 2015 </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/04/16/award.html>12 Best</li> <li /2015/04/16/award.html>All 292</li> <li /2015/04/16/award.html>Webinars</li> <li /2015/04/16/award.html>Talks</li> <li /2015/04/16/award.html>Books</li> <li /2015/04/16/award.html>Papers</li> <li /2015/04/16/award.html>Pets</li> <li /2015/04/16/award.html class=”highlighted”>Trainings</li> <li /2015/04/16/award.html>Award</li> <li /2015/04/16/award.html>Testimonials</li> <li /2015/04/16/award.html>Shift-M</li> <li /2015/04/16/award.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Software Quality Award, 2015</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
badge
<p>I’m a big fan of rules and discipline in software development; as an example, see Are You a Hacker or a Designer?. Also, I’m a big fan of object-oriented programming in its purest form; for example, see Seven Virtues of a Good Object. I’m also a co-founder and the CEO of Zerocracy, a software development company through which I put my admiration of discipline and clean design into practice.</p><p>I want to encourage you to share my passion—not just by reading this blog but through making real open source software in a disciplined way. This award is for those who are brave enough to swim against the current and value quality above everything else.</p><p>Send me your own project for review and participate in the contest.</p><p>Rules:</p><ul> <li><p>One person can submit up to three projects.</p></li> <li><p>Submissions are accepted until the **September 1, 2015** closed.</p></li> <li><p>Submissions must be sent via email to me@yegor256.com. All I need is your GitHub login and repository name; I will check the commit history to make sure you’re the main contributor to the project.</p></li> <li><p>I reserve the right to reject any submission without explanation.</p></li> <li><p>All submissions will be published on this page (including rejected ones).</p></li> <li><p>Results will be announced October 15 on this page and by email.</p></li> <li><p>The best project will receive $4,096.</p></li> <li><p>The best 8 projects will receive 1-year open source licenses to any JetBrains products (one license per project).</p></li> <li><p>Final decisions will be made by me and are not negotiable (although I may invite other people to help me make the right decision).</p></li></ul>
badge
<p>Each project must be:</p><ul> <li><p>Open source (in GitHub).</p></li> <li><p>At least 5,000 lines of code.</p></li> <li><p>At least one year old.</p></li> <li><p>Object-oriented (that’s the only thing I understand).</p></li></ul><p>The best projects will feature (more about it):</p><ul> <li><p>Strict and visible principles of design.</p></li> <li><p>Continuous delivery.</p></li> <li><p>Traceability of changes.</p></li> <li><p>Self-documented source code.</p></li> <li><p>Strict rules of code formatting.</p></li></ul><p>What doesn’t matter:</p><ul> <li><p>Popularity. Even if nobody is using your product, it is still eligible for this award. I don’t care about popularity; quality is the key.</p></li> <li><p>Programming language. I believe that any language, used correctly, can be applied to design a high-quality product.</p></li> <li><p>Buzz and trends. Even if your project is yet another parser of command line arguments, it’s still eligible for the award. I don’t care about your marketing position; quality is all.</p></li></ul><p>By the way, if you want to sponsor this award and increase the bonus, email me.</p><hr /><p>158 projects submitted so far (in order of submission):</p><ul> <li>mdbs99/AWS</li> <li>FagnerMartinsBrack/WebStories</li> <li>robertop/triumph4php</li> <li>blambeau/wlang</li> <li>alf-tool/alf-core by @blambeau</li> <li>siom79/japicmp</li> <li>tunabrain/tungsten</li> <li>AdamsLair/duality</li> <li>openra/openra by @chrisforbes</li> <li>Pacmanfan/UVDLPSlicerController</li> <li>openfurther/further-open-core by @rahuofu</li> <li>Bertram25/ValyriaTear</li> <li>odoepner/typepad</li> <li>vladmihalcea/flexy-pool</li> <li>js-cookie/js-cookie by @FagnerMartinsBrack</li> <li>jOOQ/jOOQ by @lukaseder</li> <li>raphw/byte-buddy</li> <li>uniVocity/univocity-parsers by @jbax</li> <li>arnaudroger/SimpleFlatMapper</li> <li>elBukkit/MagicPlugin by @NathanWolf</li> <li>trade-manager/trade-manager</li> <li>ParaPenguin/morphix</li> <li>tzaeschke/zoodb</li> <li>tzaeschke/critbit</li> <li>praveendath92/MDroid</li> <li>DeqingSun/ESP8266-Dash-Button</li> <li>javamonkey/beetl2.0</li> <li>81813780/HandyTabBar</li> <li>xionghuiCoder/clearpool</li> <li>android-cjj/ComicReader</li> <li>Dreampie/icedog</li> <li>hujiaweibujidao/TinyWeibo</li> <li>hujiaweibujidao/XingShan</li> <li>hujiaweibujidao/WeChat4j</li> <li>beartung/tclip-android</li> <li>beartung/insta-filter</li> <li>wewoor/ZBLOG</li> <li>gulpjs/gulp by @contra</li> <li>joedayz/titanic-javaee7</li> <li>TheCricket/Chisel-2</li> <li>ddasilva/scheme-droid</li> <li>chenjishi/SlideActivity</li> <li>yazeed44/MultiImagePicker</li> <li>wbotelhos/raty</li> <li>miku-nyan/Overchan-Android</li> <li>chylex/Hardcore-Ender-Expansion</li> <li>lionsoul2014/jcseg</li> <li>yfpeng/pengyifan-bioc</li> <li>daimor/NBStudio</li> <li>sytolk/TaxiAndroidOpen</li> <li>yaylas/AndroidFaceRecognizer</li> <li>omgware/fluid-simulator-v2</li> <li>wendykierp/JTransforms</li> <li>zqq90/webit-script</li> <li>owasp/SecurityShepherd by @markdenihan</li> <li>subchen/jetbrick-template-2x</li> <li>subchen/snack-string</li> <li>restorer/gloomy-dungeons-2</li> <li>restorer/Gloomy-Dungeons-3D</li> <li>restorer/zame-haxe-particles</li> <li>mrzl/LeapMotionP5</li> <li>relu91/niftyeditor</li> <li>bparmentier/OpenBikeSharing</li> <li>graphhopper/graphhopper by @karussell</li> <li>t-oster/VisiCut</li> <li>arnaudroger/SimpleFlatMapper</li> <li>Floens/Clover</li> <li>chrisshayan/TechLooper</li> <li>bonigarcia/dualsub</li> <li>blundell/WoodyFaceDetection</li> <li>blundell/QuickSand</li> <li>blundell/ArrowLogger</li> <li>pushtorefresh/storio by @artem-zinnatullin</li> <li>mangstadt/ez-vcard</li> <li>jmyrland/DriSMo</li> <li>pmd/pmd by @adangel</li> <li>javaslang/javaslang</li> <li>thothbot/parallax</li> <li>jasonycw/MemeCreator</li> <li>jasonycw/TyphoonTycoon</li> <li>ysc/QuestionAnsweringSystem</li> <li>ysc/word</li> <li>andot/hprose</li> <li>guikeller/jetty-runner</li> <li>frizbog/gedcom4j</li> <li>h2oai/h2o-3 by @srisatish</li> <li>Feng14/MiniWeChat-Server</li> <li>tianzhijiexian/ActivityOptionsICS</li> <li>swanson/stringer</li> <li>JayFang1993/DropDownMenu</li> <li>AizazAZ/Android-Ultra-Photo-Selector</li> <li>patilswapnilv/TerminalIDE</li> <li>zhaoqp2010/andbase</li> <li>omry/banana</li> <li>jackrex/AndroidCacheFoundation</li> <li>kaitoy/pcap4j</li> <li>rgladwell/m2e-android</li> <li>scireum/parsii</li> <li>scireum/sirius-kernel</li> <li>yazeed44/ResizableView</li> <li>yazeed44/GroceryShopping</li> <li>MindMac/AndroidAppLog</li> <li>kpbird/chips-edittext-library</li> <li>spiffyui/spiffyui</li> <li>coala-analyzer/coala by @sils1297</li> <li>mgarin/weblaf</li> <li>conductor-framework/conductor by @ddavison</li> <li>ctron/package-drone</li> <li>markkerzner/FreeEed</li> <li>morris/lessql</li> <li>jitlogic/zorka</li> <li>sdorra/angular-dashboard-framework</li> <li>iluwatar/java-design-patterns</li> <li>chesterbr/ruby2600</li> <li>testinfected/molecule</li> <li>testinfected/simple-petstore</li> <li>pchab/AndroidRTC</li> <li>dolda2000/ashd</li> <li>MaigoAkisame/MCPDict</li> <li>Ph1b/MaterialAudiobookPlayer</li> <li>SVGKit/SVGKit by @adamgit</li> <li>vertigo17/Cerberus by @bcivel</li> <li>jaredsburrows/OpenQuartz</li> <li>jaredsburrows/AndroidGradleTemplate</li> <li>vitalidze/traccar-web</li> <li>ReikaKalseki/ChromatiCraft</li> <li>ReikaKalseki/RotaryCraft</li> <li>ReikaKalseki/DragonAPI</li> <li>jOOQ/jOOX by @lukaseder</li> <li>konsoletyper/teavm</li> <li>citiususc/hipster</li> <li>katzer/cordova-plugin-local-notifications</li> <li>katzer/cordova-plugin-background-mode</li> <li>katzer/cordova-plugin-email-composer</li> <li>nivdul/actitracker-cassandra-spark</li> <li>LuckyJayce/MVCHelper</li> <li>LuckyJayce/ViewPagerIndicator</li> <li>xvik/guice-persist-orient</li> <li>xvik/dropwizard-guicey</li> <li>mbosecke/pebble</li> <li>inklabs/kommerce-core by @pdt256</li> <li>elchris/easysql</li> <li>checkstyle/checkstyle by @romani</li> <li>mifmif/mspider</li> <li>mifmif/Generex</li> <li>KeldOelykke/FailFast</li> <li>erudika/para by @albogdano</li> <li>trautonen/coveralls-maven-plugin</li> <li>mystilleef/eclipse4-smartsave</li> <li>expercise/expercise by @ufukuzun</li> <li>kbilsted/StatePrinter</li> <li>js-cookie/java-cookie by @FagnerMartinsBrack</li> <li>Suseika/inflectible</li> <li>mp911de/lettuce</li> <li>hackiftekhar/IQKeyboardManager</li> <li>mafagafogigante/dungeon</li> <li>colonB/Mixer by @kkashpur</li> <li>colonB/Dorm by @kkashpur</li></ul><hr /><p></p><p>October, 4th: A few weeks ago I asked three guys, who work with me, to check every single project in this list and provide their feedback. I’ve received three plain text files from them. Here they are, combined into one, with almost no corrections: award-2015.txt (you can find your project there). Based on their opinions, I’ve decided to select the following 12 projects for closer review (in alphabetic order):</p><ul> <li>coala-analyzer/coala</li> <li>checkstyle/checkstyle</li> <li>citiususc/hipster</li> <li>gulpjs/gulp</li> <li>kaitoy/pcap4j</li> <li>raphw/byte-buddy (added on Oct-5)</li> <li>subchen/snack-string</li> <li>gvlasov/inflectible</li> <li>testinfected/molecule</li> <li>trautonen/coveralls-maven-plugin</li> <li>wbotelhos/raty</li> <li>xvik/guice-persist-orient</li></ul><p>I’ll review them soon. The winner will be announced on the 15th of October.</p><p>October, 5th: I received an email from the author of raphw/byte-buddy, asking me to reconsider my decision about this project. I took a quick look at why the project was filtered out and decided to include it into the list of finalists. BTW, if any of you think that your project was excluded by mistake, don’t hesitate to email me.</p><p>October, 11th: I analyzed all 12 projects today. All of them are really good projects, that’s why, in order to find the best one I was focusing on their sins, not virtues. Here is what I found, preliminary.</p><p>coala-analyzer/coala (14K Python LoC, 160K HoC)</p><ul> <li>None is used in many places (over 400 places I found), which technically is NULL, and it’s a serious anti-pattern</li> <li>There are global functions, for example get_language_tool_results and DictUtilities. It is definitely a bad idea in OOP.</li> <li>Class Constants is a terrible idea.</li> <li>Checking object types in runtime is a bad idea, e.g. ClangCountVectorCreator.py</li> <li>What’s wrong with cindex.py? There are almost 3200 lines of code, that’s way too many.</li> <li>Static analysis is not a mandatory step in the build/release pipeline. That’s why, I believe, code formatting is not consistent and sometimes rather ugly. For example, pylint reports hundreds of issues. (update: scrutinizer is used, but I still believe that a local use of pylint would seriously improve the quality of code)</li> <li>Some methods have documentation, others don’t. I didn’t understand the logic. Would be great to have all methods documented. Also, not all classes are documented.</li> <li>Score: 5</li></ul><p>checkstyle/checkstyle (83K Java LoC, 553K HoC)</p><ul> <li>There are many ER-ending classes, like SeverityLevelCounter, Filter, and AbstractLoader (for example), which are anti-patterns.</li> <li>There is a whole bunch of utility classes, which are definitely a bad thing in OOP. They are even grouped into a special utils package, such a terrible idea.</li> <li>Setters and getters are everywhere, together with immutable classes, which really are not an OOP thing, for example DetectorOptions.</li> <li>NULL is actively used, in many places—it’s a serious anti-pattern</li> <li>I’ve found five .java files with over 1000 lines in each of them, for example 2500+ in ParseTreeBuilder.java</li> <li>There are direct commits to master made by different contributors and some of them are not linked back to any tickets. It’s impossible to understand why they were made. Look at this for example: 7c50922. Was there a discussion involved? Who made a decision? Not clear at all.</li> <li>Releases are not documented at all.</li> <li>Release procedure is not automated. At least I didn’t find any release script in the repository.</li> <li>Score: 3</li></ul><p>citiususc/hipster (5K Java LoC, 64K HoC)</p><ul> <li>Getters and setters are used in many places, for example in DepthFirstSearch and Transition. Aside from that, almost all classes are mutable and are used as transfer bags for the needs of the algorithm. This is not how OOP should be used, I believe.</li> <li>There are public static methods and even utility classes, for example this one, with a funny name F</li> <li>NULL is used actively, especially in iterators—it’s a bad idea</li> <li>JavaDoc documentation is not consistent, some methods are documented, others aren’t.</li> <li>Not all commits are linked to tickets, look at this, for example: 8cfa5de.</li> <li>Changes are committed directly to master branch, pull requests are not used at all.</li> <li>I didn’t find an automated procedure for release. I found one for regular snapshot deployment to Bintray, but what about releases? Are they done manually?</li> <li>There is no static analysis, that’s why the code looks messy sometimes.</li> <li>The amount of unit tests is rather small. Besides that, I didn’t find a real code coverage report published anywhere.</li> <li>Score: 4</li></ul><p>gulpjs/gulp (700 JS LoC)</p><ul> <li>This project is too small for the competition, just 700 lines of code. Disqualified.</li> <li>Score: 0</li></ul><p>kaitoy/pcap4j (42K LoC, 122K HoC)</p><ul> <li>There is a util package with utility classes, which are a bad practice</li> <li>NULL is used in mutable objects, for example in AbstractPcapAddress; it’s a bad idea</li> <li>There too many static methods and variables. They are literally everywhere. There is even a module called pcap4j-packetfactory-static, full of “classes” with static methods.</li> <li>JavaDoc documentation is not consistent and sometimes just incomplete, check this, for example</li> <li>There are just a few issues and only six pull requests. Commits are not linked to issues. There is almost zero traceability of changes.</li> <li>Release procedure is not automated, releases are not documented</li> <li>There is no static analysis, that’s why the code looks messy sometimes</li> <li>Score: 3</li></ul><p>raphw/byte-buddy (84K LoC, 503K HoC)</p><ul> <li>I found over 20 .java files with over 1000 lines of code. TypePool.java even has 6200 lines!</li> <li>There are many public static methods and properties. I realize that maybe that the only way to deal with the problem domain in Java, but still…</li> <li>instanceof is used very often, and it’s a bad practice in OOP. Again, I understand that problem domain may require it sometimes, but still…</li> <li>Most commits are made directly to master, without pull requests or tickets, that’s why traceability of them is broken.</li> <li>Release procedure is not automated (I didn’t find a script).</li> <li>Score: 5</li></ul><p>subchen/snack-string (1K LoC, 2K HoC)</p><ul> <li>The project is too small, disqualified.</li> <li>Score: 0</li></ul><p>gvlasov/inflectible (5K LoC, 36K HoC)</p><ul> <li>The project is rather small, right on the edge of competition requirements and is made by a single developer. Besides that I don’t see any problems here. The code looks object oriented, all changes are traceable back to issues and pull requests, release procedure is automated, static analysis is mandatory, releases are documented. Thumbs up!</li> <li>Score: 10</li></ul><p>testinfected/molecule (10K LoC, 43K HoC)</p><ul> <li>There are a few utility classes, for example Streams</li> <li>There are setters and getters in some classes, even through they are in a different naming convention, for example Request and Response.</li> <li>Most of .java files don’t have any JavDoc blocks, and they look consistent, but then, all of a sudden, some files do have documentation, for example WebServer.</li> <li>There are not so many issues and most of commits are not traceable back to any of them, for example b4143a0—why it was made? Not clear. Also, there are almost no pull request. Looks like the author is just committing to master.</li> <li>Release procedure is not documented/automated. I didn’t find it. Also, releases are not documented at all.</li> <li>Static analysis is absent.</li> <li>Score: 6</li></ul><p>trautonen/coveralls-maven-plugin (4.5K LoC)</p><ul> <li>The project is too small for the competition, less than 5K lines of code. Besides that, it’s younger than one year, the first commit was made in May 2015. Disqualified.</li> <li>Score: 0</li></ul><p>wbotelhos/raty (8.7K LoC, 63K HoC)</p><ul> <li>There are utility classes, for example helper.js</li> <li>There are global functions, for example in helper.js</li> <li>jasmine.js has 2400 lines of code, which is way too many</li> <li>I didn’t understand why .html files stay together with .js in the same directory, for example run.html</li> <li>Not all changes are traceable to issues, for example 0a233e8. There are not so many issues in the project and just a few pull requests.</li> <li>Release procedure is not automated (at least I didn’t find any documentation about it)</li> <li>There is no static analysis</li> <li>There are no unit tests</li> <li>Score: 2</li></ul><p>xvik/guice-persist-orient (17K LoC, 54K HoC)</p><ul> <li>There is ORM and that’s why getters and setters, for example in VersionedEntity</li> <li>Dependency injection is actively used, which, I believe, is a bad idea in OOP in general. But in this project, I understand, it is required by the problem domain. Anyway…</li> <li>There are just a few issues and almost no pull requests, and commits are not traceable back to issues, for example this one: e9c8f79</li> <li>There is no static analysis (static analysis is there, with a subset of Checkstyle, PMD and FindBugs checks)</li> <li>Score: 5</li></ul><p>I paid most attention to anti-patterns, which is the first and the most terrible sin we should try to avoid. Presence of null, for example, much more seriously affected the score than the absence of an automated release procedure.</p><p>Oct 15: Thus, we have these best projects, out of 158 submitted to the competition:</p><ol> <li>gvlasov/inflectible: winner!</li> <li>testinfected/molecule</li> <li>coala-analyzer/coala</li> <li>xvik/guice-persist-orient</li> <li>raphw/byte-buddy</li> <li>citiususc/hipster</li> <li>checkstyle/checkstyle</li> <li>kaitoy/pcap4j</li> </ol><p>Congratulations to @gvlasov, the winner! Here is your badge:</p><p>winner</p><p>Put this code into GitHub README:</p>
<pre><a href="https://www.yegor256.com/2015/04/16/award.html"> <img src="//img.teamed.io/award/2015/winner.png" style="width:203px;height:45px;" alt='winner'/></a></pre>
<p>All eight projects will receive a one-user free one-year license for one JetBrains product. I will email you all and we’ll figure out how to transfer them.</p><p>Thanks to everybody for participation! See you next year.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
badge
<p>I’m a big fan of rules and discipline in software development; as an example, see Are You a Hacker or a Designer?. Also, I’m a big fan of object-oriented programming in its purest form; for example, see Seven Virtues of a Good Object. I’m also a co-founder and the CEO of Zerocracy, a software development company through which I put my admiration of discipline and clean design into practice.</p><p>I want to encourage you to share my passion—not just by reading this blog but through making real open source software in a disciplined way. This award is for those who are brave enough to swim against the current and value quality above everything else.</p><p>Send me your own project for review and participate in the contest.</p><p>Rules:</p><ul> <li><p>One person can submit up to three projects.</p></li> <li><p>Submissions are accepted until the **September 1, 2015** closed.</p></li> <li><p>Submissions must be sent via email to me@yegor256.com. All I need is your GitHub login and repository name; I will check the commit history to make sure you’re the main contributor to the project.</p></li> <li><p>I reserve the right to reject any submission without explanation.</p></li> <li><p>All submissions will be published on this page (including rejected ones).</p></li> <li><p>Results will be announced October 15 on this page and by email.</p></li> <li><p>The best project will receive $4,096.</p></li> <li><p>The best 8 projects will receive 1-year open source licenses to any JetBrains products (one license per project).</p></li> <li><p>Final decisions will be made by me and are not negotiable (although I may invite other people to help me make the right decision).</p></li></ul>
badge
<p>Each project must be:</p><ul> <li><p>Open source (in GitHub).</p></li> <li><p>At least 5,000 lines of code.</p></li> <li><p>At least one year old.</p></li> <li><p>Object-oriented (that’s the only thing I understand).</p></li></ul><p>The best projects will feature (more about it):</p><ul> <li><p>Strict and visible principles of design.</p></li> <li><p>Continuous delivery.</p></li> <li><p>Traceability of changes.</p></li> <li><p>Self-documented source code.</p></li> <li><p>Strict rules of code formatting.</p></li></ul><p>What doesn’t matter:</p><ul> <li><p>Popularity. Even if nobody is using your product, it is still eligible for this award. I don’t care about popularity; quality is the key.</p></li> <li><p>Programming language. I believe that any language, used correctly, can be applied to design a high-quality product.</p></li> <li><p>Buzz and trends. Even if your project is yet another parser of command line arguments, it’s still eligible for the award. I don’t care about your marketing position; quality is all.</p></li></ul><p>By the way, if you want to sponsor this award and increase the bonus, email me.</p><hr /><p>158 projects submitted so far (in order of submission):</p><ul> <li>mdbs99/AWS</li> <li>FagnerMartinsBrack/WebStories</li> <li>robertop/triumph4php</li> <li>blambeau/wlang</li> <li>alf-tool/alf-core by @blambeau</li> <li>siom79/japicmp</li> <li>tunabrain/tungsten</li> <li>AdamsLair/duality</li> <li>openra/openra by @chrisforbes</li> <li>Pacmanfan/UVDLPSlicerController</li> <li>openfurther/further-open-core by @rahuofu</li> <li>Bertram25/ValyriaTear</li> <li>odoepner/typepad</li> <li>vladmihalcea/flexy-pool</li> <li>js-cookie/js-cookie by @FagnerMartinsBrack</li> <li>jOOQ/jOOQ by @lukaseder</li> <li>raphw/byte-buddy</li> <li>uniVocity/univocity-parsers by @jbax</li> <li>arnaudroger/SimpleFlatMapper</li> <li>elBukkit/MagicPlugin by @NathanWolf</li> <li>trade-manager/trade-manager</li> <li>ParaPenguin/morphix</li> <li>tzaeschke/zoodb</li> <li>tzaeschke/critbit</li> <li>praveendath92/MDroid</li> <li>DeqingSun/ESP8266-Dash-Button</li> <li>javamonkey/beetl2.0</li> <li>81813780/HandyTabBar</li> <li>xionghuiCoder/clearpool</li> <li>android-cjj/ComicReader</li> <li>Dreampie/icedog</li> <li>hujiaweibujidao/TinyWeibo</li> <li>hujiaweibujidao/XingShan</li> <li>hujiaweibujidao/WeChat4j</li> <li>beartung/tclip-android</li> <li>beartung/insta-filter</li> <li>wewoor/ZBLOG</li> <li>gulpjs/gulp by @contra</li> <li>joedayz/titanic-javaee7</li> <li>TheCricket/Chisel-2</li> <li>ddasilva/scheme-droid</li> <li>chenjishi/SlideActivity</li> <li>yazeed44/MultiImagePicker</li> <li>wbotelhos/raty</li> <li>miku-nyan/Overchan-Android</li> <li>chylex/Hardcore-Ender-Expansion</li> <li>lionsoul2014/jcseg</li> <li>yfpeng/pengyifan-bioc</li> <li>daimor/NBStudio</li> <li>sytolk/TaxiAndroidOpen</li> <li>yaylas/AndroidFaceRecognizer</li> <li>omgware/fluid-simulator-v2</li> <li>wendykierp/JTransforms</li> <li>zqq90/webit-script</li> <li>owasp/SecurityShepherd by @markdenihan</li> <li>subchen/jetbrick-template-2x</li> <li>subchen/snack-string</li> <li>restorer/gloomy-dungeons-2</li> <li>restorer/Gloomy-Dungeons-3D</li> <li>restorer/zame-haxe-particles</li> <li>mrzl/LeapMotionP5</li> <li>relu91/niftyeditor</li> <li>bparmentier/OpenBikeSharing</li> <li>graphhopper/graphhopper by @karussell</li> <li>t-oster/VisiCut</li> <li>arnaudroger/SimpleFlatMapper</li> <li>Floens/Clover</li> <li>chrisshayan/TechLooper</li> <li>bonigarcia/dualsub</li> <li>blundell/WoodyFaceDetection</li> <li>blundell/QuickSand</li> <li>blundell/ArrowLogger</li> <li>pushtorefresh/storio by @artem-zinnatullin</li> <li>mangstadt/ez-vcard</li> <li>jmyrland/DriSMo</li> <li>pmd/pmd by @adangel</li> <li>javaslang/javaslang</li> <li>thothbot/parallax</li> <li>jasonycw/MemeCreator</li> <li>jasonycw/TyphoonTycoon</li> <li>ysc/QuestionAnsweringSystem</li> <li>ysc/word</li> <li>andot/hprose</li> <li>guikeller/jetty-runner</li> <li>frizbog/gedcom4j</li> <li>h2oai/h2o-3 by @srisatish</li> <li>Feng14/MiniWeChat-Server</li> <li>tianzhijiexian/ActivityOptionsICS</li> <li>swanson/stringer</li> <li>JayFang1993/DropDownMenu</li> <li>AizazAZ/Android-Ultra-Photo-Selector</li> <li>patilswapnilv/TerminalIDE</li> <li>zhaoqp2010/andbase</li> <li>omry/banana</li> <li>jackrex/AndroidCacheFoundation</li> <li>kaitoy/pcap4j</li> <li>rgladwell/m2e-android</li> <li>scireum/parsii</li> <li>scireum/sirius-kernel</li> <li>yazeed44/ResizableView</li> <li>yazeed44/GroceryShopping</li> <li>MindMac/AndroidAppLog</li> <li>kpbird/chips-edittext-library</li> <li>spiffyui/spiffyui</li> <li>coala-analyzer/coala by @sils1297</li> <li>mgarin/weblaf</li> <li>conductor-framework/conductor by @ddavison</li> <li>ctron/package-drone</li> <li>markkerzner/FreeEed</li> <li>morris/lessql</li> <li>jitlogic/zorka</li> <li>sdorra/angular-dashboard-framework</li> <li>iluwatar/java-design-patterns</li> <li>chesterbr/ruby2600</li> <li>testinfected/molecule</li> <li>testinfected/simple-petstore</li> <li>pchab/AndroidRTC</li> <li>dolda2000/ashd</li> <li>MaigoAkisame/MCPDict</li> <li>Ph1b/MaterialAudiobookPlayer</li> <li>SVGKit/SVGKit by @adamgit</li> <li>vertigo17/Cerberus by @bcivel</li> <li>jaredsburrows/OpenQuartz</li> <li>jaredsburrows/AndroidGradleTemplate</li> <li>vitalidze/traccar-web</li> <li>ReikaKalseki/ChromatiCraft</li> <li>ReikaKalseki/RotaryCraft</li> <li>ReikaKalseki/DragonAPI</li> <li>jOOQ/jOOX by @lukaseder</li> <li>konsoletyper/teavm</li> <li>citiususc/hipster</li> <li>katzer/cordova-plugin-local-notifications</li> <li>katzer/cordova-plugin-background-mode</li> <li>katzer/cordova-plugin-email-composer</li> <li>nivdul/actitracker-cassandra-spark</li> <li>LuckyJayce/MVCHelper</li> <li>LuckyJayce/ViewPagerIndicator</li> <li>xvik/guice-persist-orient</li> <li>xvik/dropwizard-guicey</li> <li>mbosecke/pebble</li> <li>inklabs/kommerce-core by @pdt256</li> <li>elchris/easysql</li> <li>checkstyle/checkstyle by @romani</li> <li>mifmif/mspider</li> <li>mifmif/Generex</li> <li>KeldOelykke/FailFast</li> <li>erudika/para by @albogdano</li> <li>trautonen/coveralls-maven-plugin</li> <li>mystilleef/eclipse4-smartsave</li> <li>expercise/expercise by @ufukuzun</li> <li>kbilsted/StatePrinter</li> <li>js-cookie/java-cookie by @FagnerMartinsBrack</li> <li>Suseika/inflectible</li> <li>mp911de/lettuce</li> <li>hackiftekhar/IQKeyboardManager</li> <li>mafagafogigante/dungeon</li> <li>colonB/Mixer by @kkashpur</li> <li>colonB/Dorm by @kkashpur</li></ul><hr /><p></p><p>October, 4th: A few weeks ago I asked three guys, who work with me, to check every single project in this list and provide their feedback. I’ve received three plain text files from them. Here they are, combined into one, with almost no corrections: award-2015.txt (you can find your project there). Based on their opinions, I’ve decided to select the following 12 projects for closer review (in alphabetic order):</p><ul> <li>coala-analyzer/coala</li> <li>checkstyle/checkstyle</li> <li>citiususc/hipster</li> <li>gulpjs/gulp</li> <li>kaitoy/pcap4j</li> <li>raphw/byte-buddy (added on Oct-5)</li> <li>subchen/snack-string</li> <li>gvlasov/inflectible</li> <li>testinfected/molecule</li> <li>trautonen/coveralls-maven-plugin</li> <li>wbotelhos/raty</li> <li>xvik/guice-persist-orient</li></ul><p>I’ll review them soon. The winner will be announced on the 15th of October.</p><p>October, 5th: I received an email from the author of raphw/byte-buddy, asking me to reconsider my decision about this project. I took a quick look at why the project was filtered out and decided to include it into the list of finalists. BTW, if any of you think that your project was excluded by mistake, don’t hesitate to email me.</p><p>October, 11th: I analyzed all 12 projects today. All of them are really good projects, that’s why, in order to find the best one I was focusing on their sins, not virtues. Here is what I found, preliminary.</p><p>coala-analyzer/coala (14K Python LoC, 160K HoC)</p><ul> <li>None is used in many places (over 400 places I found), which technically is NULL, and it’s a serious anti-pattern</li> <li>There are global functions, for example get_language_tool_results and DictUtilities. It is definitely a bad idea in OOP.</li> <li>Class Constants is a terrible idea.</li> <li>Checking object types in runtime is a bad idea, e.g. ClangCountVectorCreator.py</li> <li>What’s wrong with cindex.py? There are almost 3200 lines of code, that’s way too many.</li> <li>Static analysis is not a mandatory step in the build/release pipeline. That’s why, I believe, code formatting is not consistent and sometimes rather ugly. For example, pylint reports hundreds of issues. (update: scrutinizer is used, but I still believe that a local use of pylint would seriously improve the quality of code)</li> <li>Some methods have documentation, others don’t. I didn’t understand the logic. Would be great to have all methods documented. Also, not all classes are documented.</li> <li>Score: 5</li></ul><p>checkstyle/checkstyle (83K Java LoC, 553K HoC)</p><ul> <li>There are many ER-ending classes, like SeverityLevelCounter, Filter, and AbstractLoader (for example), which are anti-patterns.</li> <li>There is a whole bunch of utility classes, which are definitely a bad thing in OOP. They are even grouped into a special utils package, such a terrible idea.</li> <li>Setters and getters are everywhere, together with immutable classes, which really are not an OOP thing, for example DetectorOptions.</li> <li>NULL is actively used, in many places—it’s a serious anti-pattern</li> <li>I’ve found five .java files with over 1000 lines in each of them, for example 2500+ in ParseTreeBuilder.java</li> <li>There are direct commits to master made by different contributors and some of them are not linked back to any tickets. It’s impossible to understand why they were made. Look at this for example: 7c50922. Was there a discussion involved? Who made a decision? Not clear at all.</li> <li>Releases are not documented at all.</li> <li>Release procedure is not automated. At least I didn’t find any release script in the repository.</li> <li>Score: 3</li></ul><p>citiususc/hipster (5K Java LoC, 64K HoC)</p><ul> <li>Getters and setters are used in many places, for example in DepthFirstSearch and Transition. Aside from that, almost all classes are mutable and are used as transfer bags for the needs of the algorithm. This is not how OOP should be used, I believe.</li> <li>There are public static methods and even utility classes, for example this one, with a funny name F</li> <li>NULL is used actively, especially in iterators—it’s a bad idea</li> <li>JavaDoc documentation is not consistent, some methods are documented, others aren’t.</li> <li>Not all commits are linked to tickets, look at this, for example: 8cfa5de.</li> <li>Changes are committed directly to master branch, pull requests are not used at all.</li> <li>I didn’t find an automated procedure for release. I found one for regular snapshot deployment to Bintray, but what about releases? Are they done manually?</li> <li>There is no static analysis, that’s why the code looks messy sometimes.</li> <li>The amount of unit tests is rather small. Besides that, I didn’t find a real code coverage report published anywhere.</li> <li>Score: 4</li></ul><p>gulpjs/gulp (700 JS LoC)</p><ul> <li>This project is too small for the competition, just 700 lines of code. Disqualified.</li> <li>Score: 0</li></ul><p>kaitoy/pcap4j (42K LoC, 122K HoC)</p><ul> <li>There is a util package with utility classes, which are a bad practice</li> <li>NULL is used in mutable objects, for example in AbstractPcapAddress; it’s a bad idea</li> <li>There too many static methods and variables. They are literally everywhere. There is even a module called pcap4j-packetfactory-static, full of “classes” with static methods.</li> <li>JavaDoc documentation is not consistent and sometimes just incomplete, check this, for example</li> <li>There are just a few issues and only six pull requests. Commits are not linked to issues. There is almost zero traceability of changes.</li> <li>Release procedure is not automated, releases are not documented</li> <li>There is no static analysis, that’s why the code looks messy sometimes</li> <li>Score: 3</li></ul><p>raphw/byte-buddy (84K LoC, 503K HoC)</p><ul> <li>I found over 20 .java files with over 1000 lines of code. TypePool.java even has 6200 lines!</li> <li>There are many public static methods and properties. I realize that maybe that the only way to deal with the problem domain in Java, but still…</li> <li>instanceof is used very often, and it’s a bad practice in OOP. Again, I understand that problem domain may require it sometimes, but still…</li> <li>Most commits are made directly to master, without pull requests or tickets, that’s why traceability of them is broken.</li> <li>Release procedure is not automated (I didn’t find a script).</li> <li>Score: 5</li></ul><p>subchen/snack-string (1K LoC, 2K HoC)</p><ul> <li>The project is too small, disqualified.</li> <li>Score: 0</li></ul><p>gvlasov/inflectible (5K LoC, 36K HoC)</p><ul> <li>The project is rather small, right on the edge of competition requirements and is made by a single developer. Besides that I don’t see any problems here. The code looks object oriented, all changes are traceable back to issues and pull requests, release procedure is automated, static analysis is mandatory, releases are documented. Thumbs up!</li> <li>Score: 10</li></ul><p>testinfected/molecule (10K LoC, 43K HoC)</p><ul> <li>There are a few utility classes, for example Streams</li> <li>There are setters and getters in some classes, even through they are in a different naming convention, for example Request and Response.</li> <li>Most of .java files don’t have any JavDoc blocks, and they look consistent, but then, all of a sudden, some files do have documentation, for example WebServer.</li> <li>There are not so many issues and most of commits are not traceable back to any of them, for example b4143a0—why it was made? Not clear. Also, there are almost no pull request. Looks like the author is just committing to master.</li> <li>Release procedure is not documented/automated. I didn’t find it. Also, releases are not documented at all.</li> <li>Static analysis is absent.</li> <li>Score: 6</li></ul><p>trautonen/coveralls-maven-plugin (4.5K LoC)</p><ul> <li>The project is too small for the competition, less than 5K lines of code. Besides that, it’s younger than one year, the first commit was made in May 2015. Disqualified.</li> <li>Score: 0</li></ul><p>wbotelhos/raty (8.7K LoC, 63K HoC)</p><ul> <li>There are utility classes, for example helper.js</li> <li>There are global functions, for example in helper.js</li> <li>jasmine.js has 2400 lines of code, which is way too many</li> <li>I didn’t understand why .html files stay together with .js in the same directory, for example run.html</li> <li>Not all changes are traceable to issues, for example 0a233e8. There are not so many issues in the project and just a few pull requests.</li> <li>Release procedure is not automated (at least I didn’t find any documentation about it)</li> <li>There is no static analysis</li> <li>There are no unit tests</li> <li>Score: 2</li></ul><p>xvik/guice-persist-orient (17K LoC, 54K HoC)</p><ul> <li>There is ORM and that’s why getters and setters, for example in VersionedEntity</li> <li>Dependency injection is actively used, which, I believe, is a bad idea in OOP in general. But in this project, I understand, it is required by the problem domain. Anyway…</li> <li>There are just a few issues and almost no pull requests, and commits are not traceable back to issues, for example this one: e9c8f79</li> <li>There is no static analysis (static analysis is there, with a subset of Checkstyle, PMD and FindBugs checks)</li> <li>Score: 5</li></ul><p>I paid most attention to anti-patterns, which is the first and the most terrible sin we should try to avoid. Presence of null, for example, much more seriously affected the score than the absence of an automated release procedure.</p><p>Oct 15: Thus, we have these best projects, out of 158 submitted to the competition:</p><ol> <li>gvlasov/inflectible: winner!</li> <li>testinfected/molecule</li> <li>coala-analyzer/coala</li> <li>xvik/guice-persist-orient</li> <li>raphw/byte-buddy</li> <li>citiususc/hipster</li> <li>checkstyle/checkstyle</li> <li>kaitoy/pcap4j</li> </ol><p>Congratulations to @gvlasov, the winner! Here is your badge:</p><p>winner</p><p>Put this code into GitHub README:</p>
<pre><a href="https://www.yegor256.com/2015/04/16/award.html"> <img src="//img.teamed.io/award/2015/winner.png" style="width:203px;height:45px;" alt='winner'/></a></pre>
<p>All eight projects will receive a one-user free one-year license for one JetBrains product. I will email you all and we’ll figure out how to transfer them.</p><p>Thanks to everybody for participation! See you next year.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> JAXB Is Doing It Wrong; Try Xembly </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/03/26/jaxb-vs-xembly.html>12 Best</li> <li /2015/03/26/jaxb-vs-xembly.html>All 292</li> <li /2015/03/26/jaxb-vs-xembly.html>Webinars</li> <li /2015/03/26/jaxb-vs-xembly.html>Talks</li> <li /2015/03/26/jaxb-vs-xembly.html>Books</li> <li /2015/03/26/jaxb-vs-xembly.html>Papers</li> <li /2015/03/26/jaxb-vs-xembly.html>Pets</li> <li /2015/03/26/jaxb-vs-xembly.html class=”highlighted”>Trainings</li> <li /2015/03/26/jaxb-vs-xembly.html>Award</li> <li /2015/03/26/jaxb-vs-xembly.html>Testimonials</li> <li /2015/03/26/jaxb-vs-xembly.html>Shift-M</li> <li /2015/03/26/jaxb-vs-xembly.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">JAXB Is Doing It Wrong; Try Xembly</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
badge
<p>JAXB is a 10-year-old Java technology that allows us to convert a Java object into an XML document (marshalling) and back (unmarshalling). This technology is based on setters and getters and, in my opinion, violates key principles of object-oriented programming by turning objects into passive data structures. I would recommend you use Xembly instead for marshalling Java objects into XML documents.</p><p>This is how JAXB marshalling works. Say you have a Book class that needs to be marshalled into an XML document. You have to create getters and annotate them:</p>
<pre>import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class Book { private final String isbn; private final String title; public Book(final String isbn, final String title) { this.isbn = isbn; this.title = title; } @XmlElement public String getIsbn() { return this.isbn; } @XmlElement public String getTitle() { return this.title; } }</pre>
<p>Then you create a marshaller and ask it to convert an instance of class Book into XML:</p>
<pre>final Book book = new Book("0132350882", "Clean Code"); final JAXBContext context = JAXBContext.newInstance(Book.class); final Marshaller marshaller = jaxbContext.createMarshaller(); marshaller.marshal(book, System.out);</pre>
<p>You should be expecting something like this in the output:</p>
<pre><?xml version="1.0"?> <book> <isbn>0132350882</isbn> <title>Clean Code</title> </book></pre>
<p>So what’s wrong with it? Pretty much the same thing that’s wrong with object-relational mapping, which is explained in ORM Is an Offensive Anti-Pattern. JAXB is treating an object as a bag of data, extracting the data and converting it into XML the way JAXB wants. The object has no control over this process. Therefore an object is not an object anymore but rather a passive bag of data.</p><p>An ideal approach would be to redesign our class Book this way:</p>
<pre>public class Book { private final String isbn; private final String title; public Book(final String isbn, final String title) { this.isbn = isbn; this.title = title; } public String toXML() { // create XML document and return } }</pre>
<p>However, there are a few problems with this approach. First of all, there’s massive code duplication. Building an XML document is a rather verbose process in Java. If every class had to re-implement it in its toXML() method, we would have a big problem with duplicate code.</p><p>The second problem is that we don’t know exactly what type of wrapping our XML document should be delivered in. It may be a String or an InputStream or maybe an instance of org.w3c.dom.Document. Making many toXML() methods in each object would definitely be a disaster.</p><p>Xembly provides a solution. As I’ve mentioned before, it is an imperative language for XML constructions and manipulations. Here is how we can implement our Book object with the help of Xembly:</p>
<pre>import org.xembly.Directive; public class Book { private final String isbn; private final String title; public Book(final String isbn, final String title) { this.isbn = isbn; this.title = title; } public Iterable<Directive> toXembly() { return new Directives() .add("book") .add("isbn").set(this.isbn).up() .add("title").set(this.title).up() .up(); } }</pre>
<p>Now, in order to build an XML document, we should use this code outside the object:</p>
<pre>final Book book = new Book("0132350882", "Clean Code"); final String xml = new Xembler(book.toXembly()).xml();</pre>
<p>This Xembler class will convert Xembly directives into an XML document.</p><p>The beauty of this solution is that the internals of the object are not exposed via getters and the object is fully in charge of the XML marshalling process. In addition, the complexity of these directives may be very high—much higher than the rather cumbersome annotations of JAXB.</p><p>Xembly is an open source project, so feel free to submit your questions or corrections to GitHub.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
badge
<p>JAXB is a 10-year-old Java technology that allows us to convert a Java object into an XML document (marshalling) and back (unmarshalling). This technology is based on setters and getters and, in my opinion, violates key principles of object-oriented programming by turning objects into passive data structures. I would recommend you use Xembly instead for marshalling Java objects into XML documents.</p><p>This is how JAXB marshalling works. Say you have a Book class that needs to be marshalled into an XML document. You have to create getters and annotate them:</p>
<pre>import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement public class Book { private final String isbn; private final String title; public Book(final String isbn, final String title) { this.isbn = isbn; this.title = title; } @XmlElement public String getIsbn() { return this.isbn; } @XmlElement public String getTitle() { return this.title; } }</pre>
<p>Then you create a marshaller and ask it to convert an instance of class Book into XML:</p>
<pre>final Book book = new Book("0132350882", "Clean Code"); final JAXBContext context = JAXBContext.newInstance(Book.class); final Marshaller marshaller = jaxbContext.createMarshaller(); marshaller.marshal(book, System.out);</pre>
<p>You should be expecting something like this in the output:</p>
<pre><?xml version="1.0"?> <book> <isbn>0132350882</isbn> <title>Clean Code</title> </book></pre>
<p>So what’s wrong with it? Pretty much the same thing that’s wrong with object-relational mapping, which is explained in ORM Is an Offensive Anti-Pattern. JAXB is treating an object as a bag of data, extracting the data and converting it into XML the way JAXB wants. The object has no control over this process. Therefore an object is not an object anymore but rather a passive bag of data.</p><p>An ideal approach would be to redesign our class Book this way:</p>
<pre>public class Book { private final String isbn; private final String title; public Book(final String isbn, final String title) { this.isbn = isbn; this.title = title; } public String toXML() { // create XML document and return } }</pre>
<p>However, there are a few problems with this approach. First of all, there’s massive code duplication. Building an XML document is a rather verbose process in Java. If every class had to re-implement it in its toXML() method, we would have a big problem with duplicate code.</p><p>The second problem is that we don’t know exactly what type of wrapping our XML document should be delivered in. It may be a String or an InputStream or maybe an instance of org.w3c.dom.Document. Making many toXML() methods in each object would definitely be a disaster.</p><p>Xembly provides a solution. As I’ve mentioned before, it is an imperative language for XML constructions and manipulations. Here is how we can implement our Book object with the help of Xembly:</p>
<pre>import org.xembly.Directive; public class Book { private final String isbn; private final String title; public Book(final String isbn, final String title) { this.isbn = isbn; this.title = title; } public Iterable<Directive> toXembly() { return new Directives() .add("book") .add("isbn").set(this.isbn).up() .add("title").set(this.title).up() .up(); } }</pre>
<p>Now, in order to build an XML document, we should use this code outside the object:</p>
<pre>final Book book = new Book("0132350882", "Clean Code"); final String xml = new Xembler(book.toXembly()).xml();</pre>
<p>This Xembler class will convert Xembly directives into an XML document.</p><p>The beauty of this solution is that the internals of the object are not exposed via getters and the object is fully in charge of the XML marshalling process. In addition, the complexity of these directives may be very high—much higher than the rather cumbersome annotations of JAXB.</p><p>Xembly is an open source project, so feel free to submit your questions or corrections to GitHub.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Java Web App Architecture In Takes Framework </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/03/22/takes-java-web-framework.html>12 Best</li> <li /2015/03/22/takes-java-web-framework.html>All 292</li> <li /2015/03/22/takes-java-web-framework.html>Webinars</li> <li /2015/03/22/takes-java-web-framework.html>Talks</li> <li /2015/03/22/takes-java-web-framework.html>Books</li> <li /2015/03/22/takes-java-web-framework.html>Papers</li> <li /2015/03/22/takes-java-web-framework.html>Pets</li> <li /2015/03/22/takes-java-web-framework.html class=”highlighted”>Trainings</li> <li /2015/03/22/takes-java-web-framework.html>Award</li> <li /2015/03/22/takes-java-web-framework.html>Testimonials</li> <li /2015/03/22/takes-java-web-framework.html>Shift-M</li> <li /2015/03/22/takes-java-web-framework.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Java Web App Architecture In Takes Framework</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>I used to utilize Servlets, JSP, JAX-RS, Spring Framework, Play Framework, JSF with Facelets, and a bit of Spark Framework. All of these solutions, in my humble opinion, are very far from being object-oriented and elegant. They all are full of static methods, un-testable data structures, and dirty hacks. So about a month ago, I decided to create my own Java web framework. I put a few basic principles into its foundation: 1) No NULLs, 2) no public static methods, 3) no mutable classes, and 4) no class casting, reflection, and instanceof operators. These four basic principles should guarantee clean code and transparent architecture. That’s how the Takes framework was born. Let’s see what was created and how it works.</p>
Making of The Godfather (1972) by Francis Ford Coppola<figcaption id="9fedcf46">Making of The Godfather (1972) by Francis Ford Coppola</figcaption>
<h2 id="java-web-architecture-in-a-nutshell">Java Web Architecture in a Nutshell</h2><p>This is how I understand a web application architecture and its components, in simple terms.</p><aside class="youtube"> <div class="box"> YouTube video #nheD2LNYrpk<div class="play"></div></div><div>Takes, Java Web Framework, Intro (webinar #12); 2 March 2016.</div></aside><p>First, to create a web server, we should create a new network socket, that accepts connections on a certain TCP port. Usually it is 80, but I’m going to use 8080 for testing purposes. This is done in Java with the ServerSocket class:</p>
<pre>import java.net.ServerSocket; public class Foo { public static void main(final String... args) throws Exception { final ServerSocket server = new ServerSocket(8080); while (true); } }</pre>
<p>That’s enough to start a web server. Now, the socket is ready and listening on port 8080. When someone opens http://localhost:8080 in their browser, the connection will be established and the browser will spin its waiting wheel forever. Compile this snippet and try. We just built a simple web server without the use of any frameworks. We’re not doing anything with incoming connections yet, but we’re not rejecting them either. All of them are being lined up inside that server object. It’s being done in a background thread; that’s why we need to put that while(true) in afterward. Without this endless pause, the app will finish its execution immediately and the server socket will shut down.</p><p>The next step is to accept the incoming connections. In Java, that’s done through a blocking call to the accept() method:</p>
<pre>final Socket socket = server.accept();</pre>
<p>The method is blocking its thread and waiting until a new connection arrives. As soon as that happens, it returns an instance of Socket. In order to accept the next connection, we should call accept() again. So basically, our web server should work like this:</p>
<pre>public class Foo { public static void main(final String... args) throws Exception { final ServerSocket server = new ServerSocket(8080); while (true) { final Socket socket = server.accept(); // 1. Read HTTP request from the socket // 2. Prepare an HTTP response // 3. Send HTTP response to the socket // 4. Close the socket } } }</pre>
<p>It’s an endless cycle that accepts a new connection, understands it, creates a response, returns the response, and accepts a new connection again. HTTP protocol is stateless, which means the server should not remember what happened in any previous connection. All it cares about is the incoming HTTP request in this particular connection.</p><p>The HTTP request is coming from the input stream of the socket and looks like a multi-line block of text. This is what you would see if you read an input stream of the socket:</p>
<pre>final BufferedReader reader = new BufferedReader( new InputStreamReader(socket.getInputStream()) ); while (true) { final String line = reader.readLine(); if (line.isEmpty()) { break; } System.out.println(line); }</pre>
<p>You will see something like this:</p>
<pre>GET / HTTP/1.1 Host: localhost:8080 Connection: keep-alive Cache-Control: max-age=0 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36 Accept-Encoding: gzip, deflate, sdch Accept-Language: en-US,en;q=0.8,ru;q=0.6,uk;q=0.4</pre>
<p>The client (the Google Chrome browser, for example) passes this text into the connection established. It connects to port 8080 at localhost, and as soon as the connection is ready, it immediately sends this text into it, then waits for a response.</p><p>Our job is to create an HTTP response using the information we get in the request. If our server is very primitive, we can basically ignore all the information in the request and just return “Hello, world!” to all requests (I’m using IOUtils for simplicity):</p>
<pre>import java.net.Socket; import java.net.ServerSocket; import org.apache.commons.io.IOUtils; public class Foo { public static void main(final String... args) throws Exception { final ServerSocket server = new ServerSocket(8080); while (true) { try (final Socket socket = server.accept()) { IOUtils.copy( IOUtils.toInputStream("HTTP/1.1 200 OK\r\n\r\nHello, world!"), socket.getOutputStream() ); } } } }</pre>
<p>That’s it. The server is ready. Try to compile and run it. Point your browser to http://localhost:8080, and you will see Hello, world!:</p>
<pre>$ javac -cp commons-io.jar Foo.java $ java -cp commons-io.jar:. Foo & $ curl http://localhost:8080 -v

  • Rebuilt URL to: http://localhost:8080/
  • Connected to localhost (::1) port 8080 (#0) > GET / HTTP/1.1 > User-Agent: curl/7.37.1 > Host: localhost:8080 > Accept: / > < HTTP/1.1 200 OK
  • no chunk, no close, no size. Assume close to signal end <
  • Closing connection 0 Hello, world!</code></pre></figure><p>That’s all you need to build a web server. Now let’s discuss how to make it object-oriented and composable. Let’s try to see how the Takes framework was built.</p><h2 id="routingdispatching">Routing/Dispatching</h2><p>Routing/dispatching is combined with response printing in Takes. All you need to do to create a working web application is to create a single class that implements Take interface:</p>
    <pre>import org.takes.Request; import org.takes.Take; public final class TkFoo implements Take { @Override public Response route(final Request request) { return new RsText("Hello, world!"); } }</pre>
    <p>And now it’s time to start a server:</p>
    <pre>import org.takes.http.Exit; import org.takes.http.FtBasic; public class Foo { public static void main(final String... args) throws Exception { new FtBasic(new TkFoo(), 8080).start(Exit.NEVER); } }</pre>
    <p>This FtBasic class does the exact same socket manipulations explained above. It starts a server socket on port 8080 and dispatches all incoming connections through an instance of TkFoo that we are giving to its constructor. It does this dispatching in an endless cycle, checking every second whether it’s time to stop with an instance of Exit. Obviously, Exit.NEVER always responds with, “Don’t stop, please.”</p><h2 id="http-request">HTTP Request</h2><p>Now let’s see what’s inside the HTTP request arriving at TkFoo and what we can get out of it. This is how the Request interface is defined in Takes:</p>
    <pre>public interface Request { Iterable<String> head() throws IOException; InputStream body() throws IOException; }</pre>
    <p>The request is divided into two parts: the head and the body. The head contains all lines that go before the empty line that starts a body, according to HTTP specification in RFC 2616. There are many useful decorators for Request in the framework. For example, RqMethod will help you get the method name from the first line of the header:</p>
    <pre>final String method = new RqMethod(request).method();</pre>
    <p>RqHref will help extract the query part and parse it. For example, this is the request:</p>
    <pre>GET /user?id=123 HTTP/1.1 Host: www.example.com</pre>
    <p>This code will extract that 123:</p>
    <pre>final int id = Integer.parseInt( new RqHref(request).href().param("id").get(0) );</pre>
    <p>RqPrint can get the entire request or its body printed as a String:</p>
    <pre>final String body = new RqPrint(request).printBody();</pre>
    <p>The idea here is to keep the Request interface simple and provide this request parsing functionality to its decorators. This approach helps the framework keep classes small and cohesive. Each decorator is very small and solid, doing exactly one thing. All of these decorators are in the org.takes.rq package. As you already probably understand, the Rq prefix stands for Request.</p><h2 id="first-real-web-app">First Real Web App</h2><p>Let’s create our first real web application, which will do something useful. I would recommend starting with an Entry class, which is required by Java to start an app from the command line:</p>
    <pre>import org.takes.http.Exit; import org.takes.http.FtCli; public final class Entry { public static void main(final String... args) throws Exception { new FtCli(new TkApp(), args).start(Exit.NEVER); } }</pre>
    <p>This class contains just a single main() static method that will be called by JVM when the app starts from the command line. As you see, it instantiates FtCli, giving it an instance of class TkApp and command line arguments. We’ll create the TkApp class in a second. FtCli (translates to “front-end with command line interface”) makes an instance of the same FtBasic, wrapping it into a few useful decorators and configuring it according to command line arguments. For example, --port=8080 will be converted into a 8080 port number and passed as a second argument of the FtBasic constructor.</p><p>The web application itself is called TkApp and extends TsWrap:</p>
    <pre>import org.takes.Take; import org.takes.facets.fork.FkRegex; import org.takes.facets.fork.TkFork; import org.takes.tk.TkWrap; import org.takes.tk.TkClasspath; final class TkApp extends TkWrap { TkApp() { super(TkApp.make()); } private static Take make() { return new TkFork( new FkRegex("/robots.txt", ""), new FkRegex("/css/.*", new TkClasspath()), new FkRegex("/", new TkIndex()) ); } }</pre>
    <p>We’ll discuss this TkFork class in a minute.</p><p>If you’re using Maven, this is the pom.xml you should start with:</p>
    <pre><?xml version="1.0"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>foo</groupId> <artifactId>foo</artifactId> <version>1.0-SNAPSHOT</version> <dependencies> <dependency> <groupId>org.takes</groupId> <artifactId>takes</artifactId> <version>0.9</version> <!-- check the latest in Maven Central --> </dependency> </dependencies> <build> <finalName>foo</finalName> <plugins> <plugin> <artifactId>maven-dependency-plugin</artifactId> <executions> <execution> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${project.build.directory}/deps</outputDirectory> </configuration> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <p>Running mvn clean package should build a foo.jar file in target directory and a collection of all JAR dependencies in target/deps. Now you can run the app from the command line:</p>
    <pre>$ mvn clean package $ java -Dfile.encoding=UTF-8 \ -cp ./target/foo.jar:./target/deps/* foo.Entry --port=8080</pre>
    <p>The application is ready, and you can deploy it to, say, Heroku. Just create a Procfile file in the root of the repository and push the repo to Heroku. This is what Procfile should look like:</p>
    <pre>web: java -Dfile.encoding=UTF-8 \ -cp target/foo.jar:target/deps/* \ foo.Entry --port=${PORT}</pre>
    <h2 id="tkfork">TkFork</h2><p>This TkFork class seems to be one of the core elements of the framework. It helps route an incoming HTTP request to the right take. Its logic is very simple, and there are just a few lines of code inside it. It encapsulates a collection of “forks,” which are instances of the Fork interface:</p>
    <pre>public interface Fork { Iterator<Response> route(Request req) throws IOException; }</pre>
    <p>Its only route() method either returns an empty iterator or an iterator with a single Response. TkFork goes through all forks, calling their route() methods until one of them returns a response. Once that happens, TkFork returns this response to the caller, which is FtBasic.</p><p>Let’s create a simple fork ourselves now. For example, we want to show the status of the application when the /status URL is requested. Here is the code:</p>
    <pre>final class TkApp extends TkWrap { private static Take make() { return new TkFork( new Fork() { @Override public Iterator<Response> route(Request req) { final Collection<Response> responses = new ArrayList<>(1); if (new RqHref(req).href().path().equals("/status")) { responses.add(new TkStatus()); } return responses.iterator(); } } ); } }</pre>
    <p>I believe the logic here is clear. We either return an empty iterator or an iterator with an instance of TkStatus inside. If an empty iterator is returned, TkFork will try to find another fork in the collection that actually gets an instance of Response. By the way, if nothing is found and all forks return empty iterators, TkFork will throw a “Page not found” exception.</p><p>This exact logic is implemented by an out-of-the-box fork called FkRegex, which attempts to match a request URI path with the regular expression provided:</p>
    <pre>final class TkApp extends TkWrap { private static Take make() { return new TkFork( new FkRegex("/status", new TkStatus()) ); } }</pre>
    <p>We can compose a multi-level structure of TkFork classes; for example:</p>
    <pre>final class TkApp extends TsWrap { private static Take make() { return new TkFork( new FkRegex( "/status", new TkFork( new FkParams("f", "json", new TkStatusJSON()), new FkParams("f", "xml", new TkStatusXML()) ) ) ); } }</pre>
    <p>Again, I believe it’s obvious. The instance of FkRegex will ask an encapsulated instance of TkFork to return a response, and it will try to fetch it from one that FkParams encapsulated. If the HTTP query is /status?f=xml, an instance of TkStatusXML will be returned.</p><h2 id="http-response">HTTP Response</h2><p>Now let’s discuss the structure of the HTTP response and its object-oriented abstraction, Response. This is how the interface looks:</p>
    <pre>public interface Response { Iterable<String> head() throws IOException; InputStream body() throws IOException; }</pre>
    <p>Looks very similar to the Request, doesn’t it? Well, it’s identical, mostly because the structure of the HTTP request and response is almost identical. The only difference is the first line.</p><p>There is a collection of useful decorators that help in response building. They are composable, which makes them very convenient. For example, if you want to build a response that contains an HTML page, you compose them like this:</p>
    <pre>final class TkIndex implements Take { @Override public Response act() { return new RsWithStatus( new RsWithType( new RsWithBody("<html>Hello, world!</html>"), "text/html" ), 200 ); } }</pre>
    <p>In this example, the decorator RsWithBody creates a response with a body but with no headers at all. Then, RsWithType adds the header Content-Type: text/html to it. Then, RsWithStatus makes sure the first line of the response contains HTTP/1.1 200 OK.</p><p>You can create your own decorators that can reuse existing ones. Take a look at how it’s done in RsPage from rultor.com.</p><h2 id="how-about-templates">How About Templates?</h2><p>Returning simple “Hello, world” pages is not a big problem, as we can see. But what about more complex output like HTML pages, XML documents, JSON data sets, etc? There are a few convenient Response decorators that enable all of that. Let’s start with Velocity, a simple templating engine. Well, it’s not that simple. It’s rather powerful, but I would suggest to use it in simple situations only. Here is how it works:</p>
    <pre>final class TkIndex implements Take { @Override public Response act() { return new RsVelocity("Hello, ${name}") .with("name", "Jeffrey"); } }</pre>
    <p>The RsVelocity constructor accepts a single argument that has to be a Velocity template. Then, you call the with() method, injecting data into the Velocity context. When it’s time to render the HTTP response, RsVelocity will “evaluate” the template against the context configured. Again, I would recommend you use this templating approach only for simple outputs.</p><p>For more complex HTML documents, I would recommend you use XML/XSLT in combination with Xembly. I explained this idea in a few previous posts: XML+XSLT in a Browser and RESTful API and a Web Site in the Same URL. It is simple and powerful—Java generates XML output and the XSLT processor transforms it into HTML documents. This is how we separate representation from data. The XSL stylesheet is a “view” and TkIndex is a “controller,” in terms of MVC.</p><p>I’ll write a separate article about templating with Xembly and XSL very soon.</p><p>In the meantime, we’ll create decorators for JSF/Facelets and JSP rendering in Takes. If you’re interested in helping, please fork the framework and submit your pull requests.</p><h2 id="what-about-persistence">What About Persistence?</h2><p>Now, a question that comes up is what to do with persistent entities, like databases, in-memory structures, network connections, etc. My suggestion is to initialize them inside the Entry class and pass them as arguments into the TkApp constructor. Then, the TkApp will pass them into the constructors of custom takes.</p><p>For example, we have a PostgreSQL database that contains some table data that we need to render. Here is how I would initialize a connection to it in the Entry class (I’m using a BoneCP connection pool):</p>
    <pre>public final class Entry { public static void main(final String... args) throws Exception { new FtCli(new TkApp(Entry.postgres()), args).start(Exit.NEVER); } private static Source postgres() { final BoneCPDataSource src = new BoneCPDataSource(); src.setDriverClass("org.postgresql.Driver"); src.setJdbcUrl("jdbc:postgresql://localhost/db"); src.setUser("root"); src.setPassword("super-secret-password"); return src; } }</pre>
    <p>Now, the constructor of TkApp must accept a single argument of type java.sql.Source:</p>
    <pre>final class TkApp extends TkWrap { TkApp(final Source source) { super(TkApp.make(source)); } private static Take make(final Source source) { return new TkFork( new FkRegex("/", new TkIndex(source)) ); } }</pre>
    <p>Class TkIndex also accepts a single argument of class Source. I believe you know what to do with it inside TkIndex in order to fetch the SQL table data and convert it into HTML. The point here is that the dependency must be injected into the application (instance of class TkApp) at the moment of its instantiation. This is a pure and clean dependency injection mechanism, which is absolutely container-free. Read more about it in Dependency Injection Containers Are Code Polluters.</p><h2 id="unit-testing">Unit Testing</h2><p>Since every class is immutable and all dependencies are injected only through constructors, unit testing is extremely easy. Let’s say we want to test TkStatus, which is supposed to return an HTML response (I’m using JUnit 4 and Hamcrest):</p>
    <pre>import org.junit.Test; import org.hamcrest.MatcherAssert; import org.hamcrest.Matchers; public final class TkIndexTest { @Test public void returnsHtmlPage() throws Exception { MatcherAssert.assertThat( new RsPrint( new TkStatus().act(new RqFake()) ).printBody(), Matchers.equalsTo("<html>Hello, world!</html>") ); } }</pre>
    <p>Also, we can start the entire application or any individual take in a test HTTP server and test its behavior via a real TCP socket; for example (I’m using jcabi-http to make an HTTP request and check the output):</p>
    <pre>public final class TkIndexTest { @Test public void returnsHtmlPage() throws Exception { new FtRemote(new TkIndex()).exec( new FtRemote.Script() { @Override public void exec(final URI home) throws IOException { new JdkRequest(home) .fetch() .as(RestResponse.class) .assertStatus(HttpURLConnection.HTTP_OK) .assertBody(Matchers.containsString("Hello, world!")); } } ); } }</pre>
    <p>FtRemote starts a test web server at a random TCP port and calls the exec() method at the provided instance of FtRemote.Script. The first argument of this method is a URI of the just-started web server homepage.</p><p>The architecture of Takes framework is very modular and composable. Any individual take can be tested as a standalone component, absolutely independent from the framework and other takes.</p><h2 id="why-the-name">Why the Name?</h2><p>That’s the question I’ve been hearing rather often. The idea is simple, and it originates from the movie business. When a movie is made, the crew shoots many takes in order to capture the reality and put it on film. Each capture is called a take.</p><p>In other words, a take is like a snapshot of the reality.</p><p>The same applies to this framework. Each instance of Take represents a reality at one particular moment in time. This reality is then sent to the user in the form of a Response.</p><p>PS. There are a few words about authentication: How Cookie-Based Authentication Works in the Takes Framework.</p><p>PPS. There are a few real web systems, which you may be interested to take a look at. They all are using Takes Framework and their code is open: rultor.com, jare.io, wring.io.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>I used to utilize Servlets, JSP, JAX-RS, Spring Framework, Play Framework, JSF with Facelets, and a bit of Spark Framework. All of these solutions, in my humble opinion, are very far from being object-oriented and elegant. They all are full of static methods, un-testable data structures, and dirty hacks. So about a month ago, I decided to create my own Java web framework. I put a few basic principles into its foundation: 1) No NULLs, 2) no public static methods, 3) no mutable classes, and 4) no class casting, reflection, and instanceof operators. These four basic principles should guarantee clean code and transparent architecture. That’s how the Takes framework was born. Let’s see what was created and how it works.</p>
    Making of The Godfather (1972) by Francis Ford Coppola<figcaption id="9fedcf46">Making of The Godfather (1972) by Francis Ford Coppola</figcaption>
    <h2 id="java-web-architecture-in-a-nutshell">Java Web Architecture in a Nutshell</h2><p>This is how I understand a web application architecture and its components, in simple terms.</p><aside class="youtube"> <div class="box"> YouTube video #nheD2LNYrpk<div class="play"></div></div><div>Takes, Java Web Framework, Intro (webinar #12); 2 March 2016.</div></aside><p>First, to create a web server, we should create a new network socket, that accepts connections on a certain TCP port. Usually it is 80, but I’m going to use 8080 for testing purposes. This is done in Java with the ServerSocket class:</p>
    <pre>import java.net.ServerSocket; public class Foo { public static void main(final String... args) throws Exception { final ServerSocket server = new ServerSocket(8080); while (true); } }</pre>
    <p>That’s enough to start a web server. Now, the socket is ready and listening on port 8080. When someone opens http://localhost:8080 in their browser, the connection will be established and the browser will spin its waiting wheel forever. Compile this snippet and try. We just built a simple web server without the use of any frameworks. We’re not doing anything with incoming connections yet, but we’re not rejecting them either. All of them are being lined up inside that server object. It’s being done in a background thread; that’s why we need to put that while(true) in afterward. Without this endless pause, the app will finish its execution immediately and the server socket will shut down.</p><p>The next step is to accept the incoming connections. In Java, that’s done through a blocking call to the accept() method:</p>
    <pre>final Socket socket = server.accept();</pre>
    <p>The method is blocking its thread and waiting until a new connection arrives. As soon as that happens, it returns an instance of Socket. In order to accept the next connection, we should call accept() again. So basically, our web server should work like this:</p>
    <pre>public class Foo { public static void main(final String... args) throws Exception { final ServerSocket server = new ServerSocket(8080); while (true) { final Socket socket = server.accept(); // 1. Read HTTP request from the socket // 2. Prepare an HTTP response // 3. Send HTTP response to the socket // 4. Close the socket } } }</pre>
    <p>It’s an endless cycle that accepts a new connection, understands it, creates a response, returns the response, and accepts a new connection again. HTTP protocol is stateless, which means the server should not remember what happened in any previous connection. All it cares about is the incoming HTTP request in this particular connection.</p><p>The HTTP request is coming from the input stream of the socket and looks like a multi-line block of text. This is what you would see if you read an input stream of the socket:</p>
    <pre>final BufferedReader reader = new BufferedReader( new InputStreamReader(socket.getInputStream()) ); while (true) { final String line = reader.readLine(); if (line.isEmpty()) { break; } System.out.println(line); }</pre>
    <p>You will see something like this:</p>
    <pre>GET / HTTP/1.1 Host: localhost:8080 Connection: keep-alive Cache-Control: max-age=0 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36 Accept-Encoding: gzip, deflate, sdch Accept-Language: en-US,en;q=0.8,ru;q=0.6,uk;q=0.4</pre>
    <p>The client (the Google Chrome browser, for example) passes this text into the connection established. It connects to port 8080 at localhost, and as soon as the connection is ready, it immediately sends this text into it, then waits for a response.</p><p>Our job is to create an HTTP response using the information we get in the request. If our server is very primitive, we can basically ignore all the information in the request and just return “Hello, world!” to all requests (I’m using IOUtils for simplicity):</p>
    <pre>import java.net.Socket; import java.net.ServerSocket; import org.apache.commons.io.IOUtils; public class Foo { public static void main(final String... args) throws Exception { final ServerSocket server = new ServerSocket(8080); while (true) { try (final Socket socket = server.accept()) { IOUtils.copy( IOUtils.toInputStream("HTTP/1.1 200 OK\r\n\r\nHello, world!"), socket.getOutputStream() ); } } } }</pre>
    <p>That’s it. The server is ready. Try to compile and run it. Point your browser to http://localhost:8080, and you will see Hello, world!:</p>
    <pre>$ javac -cp commons-io.jar Foo.java $ java -cp commons-io.jar:. Foo & $ curl http://localhost:8080 -v
  • Rebuilt URL to: http://localhost:8080/
  • Connected to localhost (::1) port 8080 (#0) > GET / HTTP/1.1 > User-Agent: curl/7.37.1 > Host: localhost:8080 > Accept: / > < HTTP/1.1 200 OK
  • no chunk, no close, no size. Assume close to signal end <
  • Closing connection 0 Hello, world!</code></pre></figure><p>That’s all you need to build a web server. Now let’s discuss how to make it object-oriented and composable. Let’s try to see how the Takes framework was built.</p><h2 id="routingdispatching">Routing/Dispatching</h2><p>Routing/dispatching is combined with response printing in Takes. All you need to do to create a working web application is to create a single class that implements Take interface:</p>
    <pre>import org.takes.Request; import org.takes.Take; public final class TkFoo implements Take { @Override public Response route(final Request request) { return new RsText("Hello, world!"); } }</pre>
    <p>And now it’s time to start a server:</p>
    <pre>import org.takes.http.Exit; import org.takes.http.FtBasic; public class Foo { public static void main(final String... args) throws Exception { new FtBasic(new TkFoo(), 8080).start(Exit.NEVER); } }</pre>
    <p>This FtBasic class does the exact same socket manipulations explained above. It starts a server socket on port 8080 and dispatches all incoming connections through an instance of TkFoo that we are giving to its constructor. It does this dispatching in an endless cycle, checking every second whether it’s time to stop with an instance of Exit. Obviously, Exit.NEVER always responds with, “Don’t stop, please.”</p><h2 id="http-request">HTTP Request</h2><p>Now let’s see what’s inside the HTTP request arriving at TkFoo and what we can get out of it. This is how the Request interface is defined in Takes:</p>
    <pre>public interface Request { Iterable<String> head() throws IOException; InputStream body() throws IOException; }</pre>
    <p>The request is divided into two parts: the head and the body. The head contains all lines that go before the empty line that starts a body, according to HTTP specification in RFC 2616. There are many useful decorators for Request in the framework. For example, RqMethod will help you get the method name from the first line of the header:</p>
    <pre>final String method = new RqMethod(request).method();</pre>
    <p>RqHref will help extract the query part and parse it. For example, this is the request:</p>
    <pre>GET /user?id=123 HTTP/1.1 Host: www.example.com</pre>
    <p>This code will extract that 123:</p>
    <pre>final int id = Integer.parseInt( new RqHref(request).href().param("id").get(0) );</pre>
    <p>RqPrint can get the entire request or its body printed as a String:</p>
    <pre>final String body = new RqPrint(request).printBody();</pre>
    <p>The idea here is to keep the Request interface simple and provide this request parsing functionality to its decorators. This approach helps the framework keep classes small and cohesive. Each decorator is very small and solid, doing exactly one thing. All of these decorators are in the org.takes.rq package. As you already probably understand, the Rq prefix stands for Request.</p><h2 id="first-real-web-app">First Real Web App</h2><p>Let’s create our first real web application, which will do something useful. I would recommend starting with an Entry class, which is required by Java to start an app from the command line:</p>
    <pre>import org.takes.http.Exit; import org.takes.http.FtCli; public final class Entry { public static void main(final String... args) throws Exception { new FtCli(new TkApp(), args).start(Exit.NEVER); } }</pre>
    <p>This class contains just a single main() static method that will be called by JVM when the app starts from the command line. As you see, it instantiates FtCli, giving it an instance of class TkApp and command line arguments. We’ll create the TkApp class in a second. FtCli (translates to “front-end with command line interface”) makes an instance of the same FtBasic, wrapping it into a few useful decorators and configuring it according to command line arguments. For example, --port=8080 will be converted into a 8080 port number and passed as a second argument of the FtBasic constructor.</p><p>The web application itself is called TkApp and extends TsWrap:</p>
    <pre>import org.takes.Take; import org.takes.facets.fork.FkRegex; import org.takes.facets.fork.TkFork; import org.takes.tk.TkWrap; import org.takes.tk.TkClasspath; final class TkApp extends TkWrap { TkApp() { super(TkApp.make()); } private static Take make() { return new TkFork( new FkRegex("/robots.txt", ""), new FkRegex("/css/.*", new TkClasspath()), new FkRegex("/", new TkIndex()) ); } }</pre>
    <p>We’ll discuss this TkFork class in a minute.</p><p>If you’re using Maven, this is the pom.xml you should start with:</p>
    <pre><?xml version="1.0"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>foo</groupId> <artifactId>foo</artifactId> <version>1.0-SNAPSHOT</version> <dependencies> <dependency> <groupId>org.takes</groupId> <artifactId>takes</artifactId> <version>0.9</version> <!-- check the latest in Maven Central --> </dependency> </dependencies> <build> <finalName>foo</finalName> <plugins> <plugin> <artifactId>maven-dependency-plugin</artifactId> <executions> <execution> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${project.build.directory}/deps</outputDirectory> </configuration> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <p>Running mvn clean package should build a foo.jar file in target directory and a collection of all JAR dependencies in target/deps. Now you can run the app from the command line:</p>
    <pre>$ mvn clean package $ java -Dfile.encoding=UTF-8 \ -cp ./target/foo.jar:./target/deps/* foo.Entry --port=8080</pre>
    <p>The application is ready, and you can deploy it to, say, Heroku. Just create a Procfile file in the root of the repository and push the repo to Heroku. This is what Procfile should look like:</p>
    <pre>web: java -Dfile.encoding=UTF-8 \ -cp target/foo.jar:target/deps/* \ foo.Entry --port=${PORT}</pre>
    <h2 id="tkfork">TkFork</h2><p>This TkFork class seems to be one of the core elements of the framework. It helps route an incoming HTTP request to the right take. Its logic is very simple, and there are just a few lines of code inside it. It encapsulates a collection of “forks,” which are instances of the Fork interface:</p>
    <pre>public interface Fork { Iterator<Response> route(Request req) throws IOException; }</pre>
    <p>Its only route() method either returns an empty iterator or an iterator with a single Response. TkFork goes through all forks, calling their route() methods until one of them returns a response. Once that happens, TkFork returns this response to the caller, which is FtBasic.</p><p>Let’s create a simple fork ourselves now. For example, we want to show the status of the application when the /status URL is requested. Here is the code:</p>
    <pre>final class TkApp extends TkWrap { private static Take make() { return new TkFork( new Fork() { @Override public Iterator<Response> route(Request req) { final Collection<Response> responses = new ArrayList<>(1); if (new RqHref(req).href().path().equals("/status")) { responses.add(new TkStatus()); } return responses.iterator(); } } ); } }</pre>
    <p>I believe the logic here is clear. We either return an empty iterator or an iterator with an instance of TkStatus inside. If an empty iterator is returned, TkFork will try to find another fork in the collection that actually gets an instance of Response. By the way, if nothing is found and all forks return empty iterators, TkFork will throw a “Page not found” exception.</p><p>This exact logic is implemented by an out-of-the-box fork called FkRegex, which attempts to match a request URI path with the regular expression provided:</p>
    <pre>final class TkApp extends TkWrap { private static Take make() { return new TkFork( new FkRegex("/status", new TkStatus()) ); } }</pre>
    <p>We can compose a multi-level structure of TkFork classes; for example:</p>
    <pre>final class TkApp extends TsWrap { private static Take make() { return new TkFork( new FkRegex( "/status", new TkFork( new FkParams("f", "json", new TkStatusJSON()), new FkParams("f", "xml", new TkStatusXML()) ) ) ); } }</pre>
    <p>Again, I believe it’s obvious. The instance of FkRegex will ask an encapsulated instance of TkFork to return a response, and it will try to fetch it from one that FkParams encapsulated. If the HTTP query is /status?f=xml, an instance of TkStatusXML will be returned.</p><h2 id="http-response">HTTP Response</h2><p>Now let’s discuss the structure of the HTTP response and its object-oriented abstraction, Response. This is how the interface looks:</p>
    <pre>public interface Response { Iterable<String> head() throws IOException; InputStream body() throws IOException; }</pre>
    <p>Looks very similar to the Request, doesn’t it? Well, it’s identical, mostly because the structure of the HTTP request and response is almost identical. The only difference is the first line.</p><p>There is a collection of useful decorators that help in response building. They are composable, which makes them very convenient. For example, if you want to build a response that contains an HTML page, you compose them like this:</p>
    <pre>final class TkIndex implements Take { @Override public Response act() { return new RsWithStatus( new RsWithType( new RsWithBody("<html>Hello, world!</html>"), "text/html" ), 200 ); } }</pre>
    <p>In this example, the decorator RsWithBody creates a response with a body but with no headers at all. Then, RsWithType adds the header Content-Type: text/html to it. Then, RsWithStatus makes sure the first line of the response contains HTTP/1.1 200 OK.</p><p>You can create your own decorators that can reuse existing ones. Take a look at how it’s done in RsPage from rultor.com.</p><h2 id="how-about-templates">How About Templates?</h2><p>Returning simple “Hello, world” pages is not a big problem, as we can see. But what about more complex output like HTML pages, XML documents, JSON data sets, etc? There are a few convenient Response decorators that enable all of that. Let’s start with Velocity, a simple templating engine. Well, it’s not that simple. It’s rather powerful, but I would suggest to use it in simple situations only. Here is how it works:</p>
    <pre>final class TkIndex implements Take { @Override public Response act() { return new RsVelocity("Hello, ${name}") .with("name", "Jeffrey"); } }</pre>
    <p>The RsVelocity constructor accepts a single argument that has to be a Velocity template. Then, you call the with() method, injecting data into the Velocity context. When it’s time to render the HTTP response, RsVelocity will “evaluate” the template against the context configured. Again, I would recommend you use this templating approach only for simple outputs.</p><p>For more complex HTML documents, I would recommend you use XML/XSLT in combination with Xembly. I explained this idea in a few previous posts: XML+XSLT in a Browser and RESTful API and a Web Site in the Same URL. It is simple and powerful—Java generates XML output and the XSLT processor transforms it into HTML documents. This is how we separate representation from data. The XSL stylesheet is a “view” and TkIndex is a “controller,” in terms of MVC.</p><p>I’ll write a separate article about templating with Xembly and XSL very soon.</p><p>In the meantime, we’ll create decorators for JSF/Facelets and JSP rendering in Takes. If you’re interested in helping, please fork the framework and submit your pull requests.</p><h2 id="what-about-persistence">What About Persistence?</h2><p>Now, a question that comes up is what to do with persistent entities, like databases, in-memory structures, network connections, etc. My suggestion is to initialize them inside the Entry class and pass them as arguments into the TkApp constructor. Then, the TkApp will pass them into the constructors of custom takes.</p><p>For example, we have a PostgreSQL database that contains some table data that we need to render. Here is how I would initialize a connection to it in the Entry class (I’m using a BoneCP connection pool):</p>
    <pre>public final class Entry { public static void main(final String... args) throws Exception { new FtCli(new TkApp(Entry.postgres()), args).start(Exit.NEVER); } private static Source postgres() { final BoneCPDataSource src = new BoneCPDataSource(); src.setDriverClass("org.postgresql.Driver"); src.setJdbcUrl("jdbc:postgresql://localhost/db"); src.setUser("root"); src.setPassword("super-secret-password"); return src; } }</pre>
    <p>Now, the constructor of TkApp must accept a single argument of type java.sql.Source:</p>
    <pre>final class TkApp extends TkWrap { TkApp(final Source source) { super(TkApp.make(source)); } private static Take make(final Source source) { return new TkFork( new FkRegex("/", new TkIndex(source)) ); } }</pre>
    <p>Class TkIndex also accepts a single argument of class Source. I believe you know what to do with it inside TkIndex in order to fetch the SQL table data and convert it into HTML. The point here is that the dependency must be injected into the application (instance of class TkApp) at the moment of its instantiation. This is a pure and clean dependency injection mechanism, which is absolutely container-free. Read more about it in Dependency Injection Containers Are Code Polluters.</p><h2 id="unit-testing">Unit Testing</h2><p>Since every class is immutable and all dependencies are injected only through constructors, unit testing is extremely easy. Let’s say we want to test TkStatus, which is supposed to return an HTML response (I’m using JUnit 4 and Hamcrest):</p>
    <pre>import org.junit.Test; import org.hamcrest.MatcherAssert; import org.hamcrest.Matchers; public final class TkIndexTest { @Test public void returnsHtmlPage() throws Exception { MatcherAssert.assertThat( new RsPrint( new TkStatus().act(new RqFake()) ).printBody(), Matchers.equalsTo("<html>Hello, world!</html>") ); } }</pre>
    <p>Also, we can start the entire application or any individual take in a test HTTP server and test its behavior via a real TCP socket; for example (I’m using jcabi-http to make an HTTP request and check the output):</p>
    <pre>public final class TkIndexTest { @Test public void returnsHtmlPage() throws Exception { new FtRemote(new TkIndex()).exec( new FtRemote.Script() { @Override public void exec(final URI home) throws IOException { new JdkRequest(home) .fetch() .as(RestResponse.class) .assertStatus(HttpURLConnection.HTTP_OK) .assertBody(Matchers.containsString("Hello, world!")); } } ); } }</pre>
    <p>FtRemote starts a test web server at a random TCP port and calls the exec() method at the provided instance of FtRemote.Script. The first argument of this method is a URI of the just-started web server homepage.</p><p>The architecture of Takes framework is very modular and composable. Any individual take can be tested as a standalone component, absolutely independent from the framework and other takes.</p><h2 id="why-the-name">Why the Name?</h2><p>That’s the question I’ve been hearing rather often. The idea is simple, and it originates from the movie business. When a movie is made, the crew shoots many takes in order to capture the reality and put it on film. Each capture is called a take.</p><p>In other words, a take is like a snapshot of the reality.</p><p>The same applies to this framework. Each instance of Take represents a reality at one particular moment in time. This reality is then sent to the user in the form of a Response.</p><p>PS. There are a few words about authentication: How Cookie-Based Authentication Works in the Takes Framework.</p><p>PPS. There are a few real web systems, which you may be interested to take a look at. They all are using Takes Framework and their code is open: rultor.com, jare.io, wring.io.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Composable Decorators vs. Imperative Utility Methods </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/02/26/composable-decorators.html>12 Best</li> <li /2015/02/26/composable-decorators.html>All 292</li> <li /2015/02/26/composable-decorators.html>Webinars</li> <li /2015/02/26/composable-decorators.html>Talks</li> <li /2015/02/26/composable-decorators.html>Books</li> <li /2015/02/26/composable-decorators.html>Papers</li> <li /2015/02/26/composable-decorators.html>Pets</li> <li /2015/02/26/composable-decorators.html class=”highlighted”>Trainings</li> <li /2015/02/26/composable-decorators.html>Award</li> <li /2015/02/26/composable-decorators.html>Testimonials</li> <li /2015/02/26/composable-decorators.html>Shift-M</li> <li /2015/02/26/composable-decorators.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Composable Decorators vs. Imperative Utility Methods</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>The decorator pattern is my favorite among all other patterns I’m aware of. It is a very simple and yet very powerful mechanism to make your code highly cohesive and loosely coupled. However, I believe decorators are not used often enough. They should be everywhere, but they are not. The biggest advantage we get from decorators is that they make our code composable. That’s why the title of this post is composable decorators. Unfortunately, instead of decorators, we often use imperative utility methods, which make our code procedural rather than object-oriented.</p>
    Main picture
    <p>First, a practical example. Here is an interface for an object that is supposed to read a text somewhere and return it:</p>
    <pre>interface Text { String read(); }</pre>
    <p>Here is an implementation that reads the text from a file:</p>
    <pre>final class TextInFile implements Text { private final File file; public TextInFile(final File src) { this.file = src; } @Override public String read() { return new String( Files.readAllBytes(this.file.toPath()), "UTF-8" ); } }</pre>
    <p>And now the decorator, which is another implementation of Text that removes all unprintable characters from the text:</p>
    <pre>final class PrintableText implements Text { private final Text origin; public PrintableText(final Text text) { this.origin = text; } @Override public String read() { return this.origin.read() .replaceAll("[^\p{Print}]", ""); } }</pre>
    <p>Here is how I’m using it:</p>
    <pre>final Text text = new PrintableText( new TextInFile(new File("/tmp/a.txt")) ); String content = text.read();</pre>
    <p>As you can see, the PrintableText doesn’t read the text from the file. It doesn’t really care where the text is coming from. It delegates text reading to the encapsulated instance of Text. How this encapsulated object will deal with the text and where it will get it doesn’t concern PrintableText.</p><p>Let’s continue and try to create an implementation of Text that will capitalize all letters in the text:</p>
    <pre>final class AllCapsText implements Text { private final Text origin; public AllCapsText(final Text text) { this.origin = text; } @Override public String read() { return this.origin.read().toUpperCase(Locale.ENGLISH); } }</pre>
    <p>How about a Text that trims the input:</p>
    <pre>final class TrimmedText implements Text { private final Text origin; public TrimmedText(final Text text) { this.origin = text; } @Override public String read() { return this.origin.read().trim(); } }</pre>
    <aside class="youtube"> <div class="box"> YouTube video #D0dqC_3Bch8<div class="play"></div></div><div>Objects vs. Static Methods (webinar #1); 8 April 2015.</div></aside><p>I can go on and on with these decorators. I can create many of them, suitable for their own individual use cases. But let’s see how they all can play together. Let’s say I want to read the text from the file, capitalize it, trim it, and remove all unprintable characters. And I want to be declarative. Here is what I do:</p>
    <pre>final Text text = new AllCapsText( new TrimmedText( new PrintableText( new TextInFile(new File("/tmp/a.txt")) ) ) ); String content = text.read();</pre>
    <p>First, I create an instance of Text, composing multiple decorators into a single object. I declaratively define the behavior of text without actually executing anything. Until method read() is called, the file is not touched and the processing of the text is not started. The object text is just a composition of decorators, not an executable procedure. Check out this article about declarative and imperative styles of programming: Utility Classes Have Nothing to Do With Functional Programming.</p><p>This design is much more flexible and reusable than a more traditional one, where the Text object is smart enough to perform all said operations. For example, class String from Java is a good example of a bad design. It has more than 20 utility methods that should have been provided as decorators instead: trim(), toUpperCase(), substring(), split(), and many others, for example. When I want to trim my string, uppercase it, and then split it into pieces, here is what my code will look like:</p>
    <pre>final String txt = "hello, world!"; final String[] parts = txt.trim().toUpperCase().split(" ");</pre>
    <p>This is imperative and procedural programming. Composable decorators, on the other hand, would make this code object-oriented and declarative. Something like this would be great to have in Java instead (pseudo-code):</p>
    <pre>final String[] parts = new String.Split( new String.UpperCased( new String.Trimmed("hello, world!") ) );</pre>
    <p>To conclude, I recommend you think twice every time you add a new utility method to the interface/class. Try to avoid utility methods as much as possible, and use decorators instead. An ideal interface should contain only methods that you absolutely cannot remove. Everything else should be done through composable decorators.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>The decorator pattern is my favorite among all other patterns I’m aware of. It is a very simple and yet very powerful mechanism to make your code highly cohesive and loosely coupled. However, I believe decorators are not used often enough. They should be everywhere, but they are not. The biggest advantage we get from decorators is that they make our code composable. That’s why the title of this post is composable decorators. Unfortunately, instead of decorators, we often use imperative utility methods, which make our code procedural rather than object-oriented.</p>
    Main picture
    <p>First, a practical example. Here is an interface for an object that is supposed to read a text somewhere and return it:</p>
    <pre>interface Text { String read(); }</pre>
    <p>Here is an implementation that reads the text from a file:</p>
    <pre>final class TextInFile implements Text { private final File file; public TextInFile(final File src) { this.file = src; } @Override public String read() { return new String( Files.readAllBytes(this.file.toPath()), "UTF-8" ); } }</pre>
    <p>And now the decorator, which is another implementation of Text that removes all unprintable characters from the text:</p>
    <pre>final class PrintableText implements Text { private final Text origin; public PrintableText(final Text text) { this.origin = text; } @Override public String read() { return this.origin.read() .replaceAll("[^\p{Print}]", ""); } }</pre>
    <p>Here is how I’m using it:</p>
    <pre>final Text text = new PrintableText( new TextInFile(new File("/tmp/a.txt")) ); String content = text.read();</pre>
    <p>As you can see, the PrintableText doesn’t read the text from the file. It doesn’t really care where the text is coming from. It delegates text reading to the encapsulated instance of Text. How this encapsulated object will deal with the text and where it will get it doesn’t concern PrintableText.</p><p>Let’s continue and try to create an implementation of Text that will capitalize all letters in the text:</p>
    <pre>final class AllCapsText implements Text { private final Text origin; public AllCapsText(final Text text) { this.origin = text; } @Override public String read() { return this.origin.read().toUpperCase(Locale.ENGLISH); } }</pre>
    <p>How about a Text that trims the input:</p>
    <pre>final class TrimmedText implements Text { private final Text origin; public TrimmedText(final Text text) { this.origin = text; } @Override public String read() { return this.origin.read().trim(); } }</pre>
    <aside class="youtube"> <div class="box"> YouTube video #D0dqC_3Bch8<div class="play"></div></div><div>Objects vs. Static Methods (webinar #1); 8 April 2015.</div></aside><p>I can go on and on with these decorators. I can create many of them, suitable for their own individual use cases. But let’s see how they all can play together. Let’s say I want to read the text from the file, capitalize it, trim it, and remove all unprintable characters. And I want to be declarative. Here is what I do:</p>
    <pre>final Text text = new AllCapsText( new TrimmedText( new PrintableText( new TextInFile(new File("/tmp/a.txt")) ) ) ); String content = text.read();</pre>
    <p>First, I create an instance of Text, composing multiple decorators into a single object. I declaratively define the behavior of text without actually executing anything. Until method read() is called, the file is not touched and the processing of the text is not started. The object text is just a composition of decorators, not an executable procedure. Check out this article about declarative and imperative styles of programming: Utility Classes Have Nothing to Do With Functional Programming.</p><p>This design is much more flexible and reusable than a more traditional one, where the Text object is smart enough to perform all said operations. For example, class String from Java is a good example of a bad design. It has more than 20 utility methods that should have been provided as decorators instead: trim(), toUpperCase(), substring(), split(), and many others, for example. When I want to trim my string, uppercase it, and then split it into pieces, here is what my code will look like:</p>
    <pre>final String txt = "hello, world!"; final String[] parts = txt.trim().toUpperCase().split(" ");</pre>
    <p>This is imperative and procedural programming. Composable decorators, on the other hand, would make this code object-oriented and declarative. Something like this would be great to have in Java instead (pseudo-code):</p>
    <pre>final String[] parts = new String.Split( new String.UpperCased( new String.Trimmed("hello, world!") ) );</pre>
    <p>To conclude, I recommend you think twice every time you add a new utility method to the interface/class. Try to avoid utility methods as much as possible, and use decorators instead. An ideal interface should contain only methods that you absolutely cannot remove. Everything else should be done through composable decorators.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> A Haircut </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/02/23/haircut.html>12 Best</li> <li /2015/02/23/haircut.html>All 292</li> <li /2015/02/23/haircut.html>Webinars</li> <li /2015/02/23/haircut.html>Talks</li> <li /2015/02/23/haircut.html>Books</li> <li /2015/02/23/haircut.html>Papers</li> <li /2015/02/23/haircut.html>Pets</li> <li /2015/02/23/haircut.html class=”highlighted”>Trainings</li> <li /2015/02/23/haircut.html>Award</li> <li /2015/02/23/haircut.html>Testimonials</li> <li /2015/02/23/haircut.html>Shift-M</li> <li /2015/02/23/haircut.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">A Haircut</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>I received a haircut today, and the niceness of my hairdresser led him to fill the appointment with courteous questions about how I wanted my hair cut, what size of clipper he should use, how long the sides should be, and how much should be removed from the front. He also offered me many types of shampoo and a cup of tea. All this reminded me of the work we do as programmers, and I decided to write a short post about it. I’ve already mentioned before that trying to make a customer happy is a false objective. This hairdresser was a perfect illustrative example of this very mistake. By the way, in the end, I wasn’t happy, and he got no tip. How could this happen if he was so friendly and nice?</p>
    The Man Who Wasn't There (2001) by Coen Brothers<figcaption id="243d0d7c">The Man Who Wasn't There (2001) by Coen Brothers</figcaption>
    <p>I’m not a hairdresser, and I have very little understanding of how to deal with hair. I came to him because I assumed he knew more about this business than I did. I chose him through the assistance of Yelp. I wanted him to tell me how long the hair on the sides should be and how much should be removed on the top. I expected him to give me his professional judgment and stand by it.</p><p>Instead of asking me how much I wanted removed on the sides, he should have told me there should be less on the sides. This is what a true professional would do. A true professional would give me his vision of the haircut that best suits me and would try to convince me that it was the best choice.</p><aside class="quote">He tried to please me. In the end, he lost.</aside><p>A true professional would not ask me but would tell me instead, because he would understand that my goal was not to boss him around and make him do my hair the way I wanted it. My goal was to get the best out of his professional skill.</p><p>Unfortunately, the guy was either weak or immature. He didn’t argue with me and didn’t try to convince me. He tried to please me. In the end, he lost.</p><p>Exactly the same thing happens when we ask our customers about the technologies they want us to use. I hear this question very often: What language do you want us to use (meaning Java or Ruby or something else)? Or what database should we use? Or how do you want us to design this?</p><p>Don’t do that. Don’t lose like that hairdresser. Don’t ask your clients what they want. Instead, learn their business requirements and then suggest the solution you think is the best for them. Then, insist and argue if they don’t agree. Convince them. Even if they fire you in the end for your stubbornness, it’s better than being that hairdresser who is doomed to please every single client without getting anywhere further.</p><p>Remember, the client is not the king; his hairs are.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>I received a haircut today, and the niceness of my hairdresser led him to fill the appointment with courteous questions about how I wanted my hair cut, what size of clipper he should use, how long the sides should be, and how much should be removed from the front. He also offered me many types of shampoo and a cup of tea. All this reminded me of the work we do as programmers, and I decided to write a short post about it. I’ve already mentioned before that trying to make a customer happy is a false objective. This hairdresser was a perfect illustrative example of this very mistake. By the way, in the end, I wasn’t happy, and he got no tip. How could this happen if he was so friendly and nice?</p>
    The Man Who Wasn't There (2001) by Coen Brothers<figcaption id="243d0d7c">The Man Who Wasn't There (2001) by Coen Brothers</figcaption>
    <p>I’m not a hairdresser, and I have very little understanding of how to deal with hair. I came to him because I assumed he knew more about this business than I did. I chose him through the assistance of Yelp. I wanted him to tell me how long the hair on the sides should be and how much should be removed on the top. I expected him to give me his professional judgment and stand by it.</p><p>Instead of asking me how much I wanted removed on the sides, he should have told me there should be less on the sides. This is what a true professional would do. A true professional would give me his vision of the haircut that best suits me and would try to convince me that it was the best choice.</p><aside class="quote">He tried to please me. In the end, he lost.</aside><p>A true professional would not ask me but would tell me instead, because he would understand that my goal was not to boss him around and make him do my hair the way I wanted it. My goal was to get the best out of his professional skill.</p><p>Unfortunately, the guy was either weak or immature. He didn’t argue with me and didn’t try to convince me. He tried to please me. In the end, he lost.</p><p>Exactly the same thing happens when we ask our customers about the technologies they want us to use. I hear this question very often: What language do you want us to use (meaning Java or Ruby or something else)? Or what database should we use? Or how do you want us to design this?</p><p>Don’t do that. Don’t lose like that hairdresser. Don’t ask your clients what they want. Instead, learn their business requirements and then suggest the solution you think is the best for them. Then, insist and argue if they don’t agree. Convince them. Even if they fire you in the end for your stubbornness, it’s better than being that hairdresser who is doomed to please every single client without getting anywhere further.</p><p>Remember, the client is not the king; his hairs are.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Utility Classes Have Nothing to Do With Functional Programming </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>12 Best</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>All 292</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Webinars</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Talks</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Books</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Papers</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Pets</li> <li /2015/02/20/utility-classes-vs-functional-programming.html class=”highlighted”>Trainings</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Award</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Testimonials</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Shift-M</li> <li /2015/02/20/utility-classes-vs-functional-programming.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Utility Classes Have Nothing to Do With Functional Programming</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>I was recently accused of being against functional programming because I call utility classes an anti-pattern. That’s absolutely wrong! Well, I do consider them a terrible anti-pattern, but they have nothing to do with functional programming. I believe there are two basic reasons why. First, functional programming is declarative, while utility class methods are imperative. Second, functional programming is based on lambda calculus, where a function can be assigned to a variable. Utility class methods are not functions in this sense. I’ll decode these statements in a minute.</p><p>In Java, there are basically two valid alternatives to these ugly utility classes aggressively promoted by Guava, Apache Commons, and others. The first one is the use of traditional classes, and the second one is Java 8 lambda. Now let’s see why utility classes are not even close to functional programming and where this misconception is coming from.</p>
    Color Me Kubrick (2005) by Brian W. Cook<figcaption id="56d1f92f">Color Me Kubrick (2005) by Brian W. Cook</figcaption>
    <p>Here is a typical example of a utility class Math from Java 1.0:</p>
    <pre>public class Math { public static double abs(double a); // a few dozens of other methods of the same style }</pre>
    <p>Here is how you would use it when you want to calculate an absolute value of a floating point number:</p>
    <pre>double x = Math.abs(3.1415926d);</pre>
    <aside class="quote">The code will work, but it is not object-oriented programming</aside><p>What’s wrong with it? We need a function, and we get it from class Math. The class has many useful functions inside it that can be used for many typical mathematical operations, like calculating maximum, minimum, sine, cosine, etc. It is a very popular concept; just look at any commercial or open source product. These utility classes are used everywhere since Java was invented (this Math class was introduced in Java’s first version). Well, technically there is nothing wrong. The code will work. But it is not object-oriented programming. Instead, it is imperative and procedural. Do we care? Well, it’s up to you to decide. Let’s see what the difference is.</p><aside class="youtube"> <div class="box"> YouTube video #D0dqC_3Bch8<div class="play"></div></div><div>Objects vs. Static Methods (webinar #1); 8 April 2015.</div></aside><p>There are basically two different approaches: declarative and imperative.</p><p>Imperative programming is focused on describing how a program operates in terms of statements that change a program state. We just saw an example of imperative programming above. Here is another (this is pure imperative/procedural programming that has nothing to do with OOP):</p>
    <pre>public class MyMath { public double f(double a, double b) { double max = Math.max(a, b); double x = Math.abs(max); return x; } }</pre>
    <p>Declarative programming focuses on what the program should accomplish without prescribing how to do it in terms of sequences of actions to be taken. This is how the same code would look in Lisp, a functional programming language:</p>
    <pre>(defun f (a b) (abs (max a b)))</pre>
    <p>What’s the catch? Just a difference in syntax? Not really.</p><p>There are many definitions of the difference between imperative and declarative styles, but I will try to give my own. There are basically three roles interacting in the scenario with this f function/method: a buyer, a packager of the result, and a consumer of the result. Let’s say I call this function like this:</p>
    <pre>public void foo() { double x = this.calc(5, -7); System.out.println("max+abs equals to " + x); } private double calc(double a, double b) { double x = Math.f(a, b); return x; }</pre>
    <p>Here, method calc() is a buyer, method Math.f() is a packager of the result, and method foo() is a consumer. No matter which programming style is used, there are always these three guys participating in the process: the buyer, the packager, and the consumer.</p><aside class="youtube"> <div class="box"> YouTube video #psrp3TtaYYI<div class="play"></div></div><div>What’s Wrong About Utility Classes? (webinar #6); 2 September 2015.</div></aside><p>Imagine you’re a buyer and want to purchase a gift for your (girl|boy)friend. The first option is to visit a shop, pay $50, let them package that perfume for you, and then deliver it to the friend (and get a kiss in return). This is an imperative style.</p><p>The second option is to visit a shop, pay $50, and get a gift card. You then present this card to the friend (and get a kiss in return). When he or she decides to convert it to perfume, he or she will visit the shop and get it. This is a declarative style.</p><p>See the difference?</p><p>In the first case, which is imperative, you force the packager (a beauty shop) to find that perfume in stock, package it, and present it to you as a ready-to-be-used product. In the second scenario, which is declarative, you’re just getting a promise from the shop that eventually, when it’s necessary, the staff will find the perfume in stock, package it, and provide it to those who need it. If your friend never visits the shop with that gift card, the perfume will remain in stock.</p><p>Moreover, your friend can use that gift card as a product itself, never visiting the shop. He or she may instead present it to somebody else as a gift or just exchange it for another card or product. The gift card itself becomes a product!</p><p>So the difference is what the consumer is getting—either a product ready to be used (imperative) or a voucher for the product, which can later be converted into a real product (declarative).</p><p>Utility classes, like Math from JDK or StringUtils from Apache Commons, return products ready to be used immediately, while functions in Lisp and other functional languages return “vouchers.” For example, if you call the max function in Lisp, the actual maximum between two numbers will only be calculated when you actually start using it:</p>
    <pre>(let (x (max 1 5)) (print "X equals to " x))</pre>
    <p>Until this print actually starts to output characters to the screen, the function max won’t be called. This x is a “voucher” returned to you when you attempted to “buy” a maximum between 1 and 5.</p><p>Note, however, that nesting Java static functions one into another doesn’t make them declarative. The code is still imperative, because its execution delivers the result here and now:</p>
    <pre>public class MyMath { public double f(double a, double b) { return Math.abs(Math.max(a, b)); } }</pre>
    <p>“Okay,” you may say, “I got it, but why is declarative style better than imperative? What’s the big deal?” I’m getting to it. Let me first show the difference between functions in functional programming and static methods in OOP. As mentioned above, this is the second big difference between utility classes and functional programming.</p><p>In any functional programming language, you can do this:</p>
    <pre>(defun foo (x) (x 5))</pre>
    <p>Then, later, you can call that x:</p>
    <pre>(defun bar (x) (+ x 1)) // defining function bar (print (foo bar)) // passing bar as an argument to foo</pre>
    <p>Static methods in Java are not functions in terms of functional programming. You can’t do anything like this with a static method. You can’t pass a static method as an argument to another method. Basically, static methods are procedures or, simply put, Java statements grouped under a unique name. The only way to access them is to call a procedure and pass all necessary arguments to it. The procedure will calculate something and return a result that is immediately ready for usage.</p><p>And now we’re getting to the final question I can hear you asking: “Okay, utility classes are not functional programming, but they look like functional programming, they work very fast, and they are very easy to use. Why not use them? Why aim for perfection when 20 years of Java history proves that utility classes are the main instrument of each Java developer?”</p><p>Besides OOP fundamentalism, which I’m very often accused of, there are a few very practical reasons (BTW, I am an OOP fundamentalist):</p><ul> <li><p>Testability. Calls to static methods in utility classes are hard-coded dependencies that can never be broken for testing purposes. If your class is calling FileUtils.readFile(), I will never be able to test it without using a real file on disk.</p></li> <li><p>Efficiency. Utility classes, due to their imperative nature, are much less efficient than their declarative alternatives. They simply do all calculations right here and now, taking processor resources even when it’s not yet necessary. Instead of returning a promise to break down a string into chunks, StringUtils.split() breaks it down right now. And it breaks it down into all possible chunks, even if only the first one is required by the “buyer.”</p></li> <li><p>Readability. Utility classes tend to be huge (try to read the source code of StringUtils or FileUtils from Apache Commons). The entire idea of separation of concerns, which makes OOP so beautiful, is absent in utility classes. They just put all possible procedures into one huge .java file, which becomes absolutely unmaintainable when it surpasses a dozen static methods.</p></li></ul><p>To conclude, let me reiterate: Utility classes have nothing to do with functional programming. They are simply bags of static methods, which are imperative procedures. Try to stay as far as possible away from them and use solid, cohesive objects no matter how many of them you have to declare and how small they are.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>I was recently accused of being against functional programming because I call utility classes an anti-pattern. That’s absolutely wrong! Well, I do consider them a terrible anti-pattern, but they have nothing to do with functional programming. I believe there are two basic reasons why. First, functional programming is declarative, while utility class methods are imperative. Second, functional programming is based on lambda calculus, where a function can be assigned to a variable. Utility class methods are not functions in this sense. I’ll decode these statements in a minute.</p><p>In Java, there are basically two valid alternatives to these ugly utility classes aggressively promoted by Guava, Apache Commons, and others. The first one is the use of traditional classes, and the second one is Java 8 lambda. Now let’s see why utility classes are not even close to functional programming and where this misconception is coming from.</p>
    Color Me Kubrick (2005) by Brian W. Cook<figcaption id="56d1f92f">Color Me Kubrick (2005) by Brian W. Cook</figcaption>
    <p>Here is a typical example of a utility class Math from Java 1.0:</p>
    <pre>public class Math { public static double abs(double a); // a few dozens of other methods of the same style }</pre>
    <p>Here is how you would use it when you want to calculate an absolute value of a floating point number:</p>
    <pre>double x = Math.abs(3.1415926d);</pre>
    <aside class="quote">The code will work, but it is not object-oriented programming</aside><p>What’s wrong with it? We need a function, and we get it from class Math. The class has many useful functions inside it that can be used for many typical mathematical operations, like calculating maximum, minimum, sine, cosine, etc. It is a very popular concept; just look at any commercial or open source product. These utility classes are used everywhere since Java was invented (this Math class was introduced in Java’s first version). Well, technically there is nothing wrong. The code will work. But it is not object-oriented programming. Instead, it is imperative and procedural. Do we care? Well, it’s up to you to decide. Let’s see what the difference is.</p><aside class="youtube"> <div class="box"> YouTube video #D0dqC_3Bch8<div class="play"></div></div><div>Objects vs. Static Methods (webinar #1); 8 April 2015.</div></aside><p>There are basically two different approaches: declarative and imperative.</p><p>Imperative programming is focused on describing how a program operates in terms of statements that change a program state. We just saw an example of imperative programming above. Here is another (this is pure imperative/procedural programming that has nothing to do with OOP):</p>
    <pre>public class MyMath { public double f(double a, double b) { double max = Math.max(a, b); double x = Math.abs(max); return x; } }</pre>
    <p>Declarative programming focuses on what the program should accomplish without prescribing how to do it in terms of sequences of actions to be taken. This is how the same code would look in Lisp, a functional programming language:</p>
    <pre>(defun f (a b) (abs (max a b)))</pre>
    <p>What’s the catch? Just a difference in syntax? Not really.</p><p>There are many definitions of the difference between imperative and declarative styles, but I will try to give my own. There are basically three roles interacting in the scenario with this f function/method: a buyer, a packager of the result, and a consumer of the result. Let’s say I call this function like this:</p>
    <pre>public void foo() { double x = this.calc(5, -7); System.out.println("max+abs equals to " + x); } private double calc(double a, double b) { double x = Math.f(a, b); return x; }</pre>
    <p>Here, method calc() is a buyer, method Math.f() is a packager of the result, and method foo() is a consumer. No matter which programming style is used, there are always these three guys participating in the process: the buyer, the packager, and the consumer.</p><aside class="youtube"> <div class="box"> YouTube video #psrp3TtaYYI<div class="play"></div></div><div>What’s Wrong About Utility Classes? (webinar #6); 2 September 2015.</div></aside><p>Imagine you’re a buyer and want to purchase a gift for your (girl|boy)friend. The first option is to visit a shop, pay $50, let them package that perfume for you, and then deliver it to the friend (and get a kiss in return). This is an imperative style.</p><p>The second option is to visit a shop, pay $50, and get a gift card. You then present this card to the friend (and get a kiss in return). When he or she decides to convert it to perfume, he or she will visit the shop and get it. This is a declarative style.</p><p>See the difference?</p><p>In the first case, which is imperative, you force the packager (a beauty shop) to find that perfume in stock, package it, and present it to you as a ready-to-be-used product. In the second scenario, which is declarative, you’re just getting a promise from the shop that eventually, when it’s necessary, the staff will find the perfume in stock, package it, and provide it to those who need it. If your friend never visits the shop with that gift card, the perfume will remain in stock.</p><p>Moreover, your friend can use that gift card as a product itself, never visiting the shop. He or she may instead present it to somebody else as a gift or just exchange it for another card or product. The gift card itself becomes a product!</p><p>So the difference is what the consumer is getting—either a product ready to be used (imperative) or a voucher for the product, which can later be converted into a real product (declarative).</p><p>Utility classes, like Math from JDK or StringUtils from Apache Commons, return products ready to be used immediately, while functions in Lisp and other functional languages return “vouchers.” For example, if you call the max function in Lisp, the actual maximum between two numbers will only be calculated when you actually start using it:</p>
    <pre>(let (x (max 1 5)) (print "X equals to " x))</pre>
    <p>Until this print actually starts to output characters to the screen, the function max won’t be called. This x is a “voucher” returned to you when you attempted to “buy” a maximum between 1 and 5.</p><p>Note, however, that nesting Java static functions one into another doesn’t make them declarative. The code is still imperative, because its execution delivers the result here and now:</p>
    <pre>public class MyMath { public double f(double a, double b) { return Math.abs(Math.max(a, b)); } }</pre>
    <p>“Okay,” you may say, “I got it, but why is declarative style better than imperative? What’s the big deal?” I’m getting to it. Let me first show the difference between functions in functional programming and static methods in OOP. As mentioned above, this is the second big difference between utility classes and functional programming.</p><p>In any functional programming language, you can do this:</p>
    <pre>(defun foo (x) (x 5))</pre>
    <p>Then, later, you can call that x:</p>
    <pre>(defun bar (x) (+ x 1)) // defining function bar (print (foo bar)) // passing bar as an argument to foo</pre>
    <p>Static methods in Java are not functions in terms of functional programming. You can’t do anything like this with a static method. You can’t pass a static method as an argument to another method. Basically, static methods are procedures or, simply put, Java statements grouped under a unique name. The only way to access them is to call a procedure and pass all necessary arguments to it. The procedure will calculate something and return a result that is immediately ready for usage.</p><p>And now we’re getting to the final question I can hear you asking: “Okay, utility classes are not functional programming, but they look like functional programming, they work very fast, and they are very easy to use. Why not use them? Why aim for perfection when 20 years of Java history proves that utility classes are the main instrument of each Java developer?”</p><p>Besides OOP fundamentalism, which I’m very often accused of, there are a few very practical reasons (BTW, I am an OOP fundamentalist):</p><ul> <li><p>Testability. Calls to static methods in utility classes are hard-coded dependencies that can never be broken for testing purposes. If your class is calling FileUtils.readFile(), I will never be able to test it without using a real file on disk.</p></li> <li><p>Efficiency. Utility classes, due to their imperative nature, are much less efficient than their declarative alternatives. They simply do all calculations right here and now, taking processor resources even when it’s not yet necessary. Instead of returning a promise to break down a string into chunks, StringUtils.split() breaks it down right now. And it breaks it down into all possible chunks, even if only the first one is required by the “buyer.”</p></li> <li><p>Readability. Utility classes tend to be huge (try to read the source code of StringUtils or FileUtils from Apache Commons). The entire idea of separation of concerns, which makes OOP so beautiful, is absent in utility classes. They just put all possible procedures into one huge .java file, which becomes absolutely unmaintainable when it surpasses a dozen static methods.</p></li></ul><p>To conclude, let me reiterate: Utility classes have nothing to do with functional programming. They are simply bags of static methods, which are imperative procedures. Try to stay as far as possible away from them and use solid, cohesive objects no matter how many of them you have to declare and how small they are.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Code For the User, Not for Yourself </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/02/12/top-down-design.html>12 Best</li> <li /2015/02/12/top-down-design.html>All 292</li> <li /2015/02/12/top-down-design.html>Webinars</li> <li /2015/02/12/top-down-design.html>Talks</li> <li /2015/02/12/top-down-design.html>Books</li> <li /2015/02/12/top-down-design.html>Papers</li> <li /2015/02/12/top-down-design.html>Pets</li> <li /2015/02/12/top-down-design.html class=”highlighted”>Trainings</li> <li /2015/02/12/top-down-design.html>Award</li> <li /2015/02/12/top-down-design.html>Testimonials</li> <li /2015/02/12/top-down-design.html>Shift-M</li> <li /2015/02/12/top-down-design.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Code For the User, Not for Yourself</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>First, no matter what the methodology is, we all write software for our users (a.k.a. customers, project sponsors, end users, or clients). Second, no matter what the methodology is, we write incrementally, releasing features and bug fixes one by one. Maybe I’m saying something absolutely obvious here, but it’s important to remember that each new version should first of all satisfy the needs of the user, not of us programmers. In other words, the way we decompose a big task into smaller pieces should be user-targeted, and that’s why you always work top down. Let’s see what I mean through a practical example.</p>
    Delicatessen (1991) by Jean-Pierre Jeunet<figcaption id="077c7d62">Delicatessen (1991) by Jean-Pierre Jeunet</figcaption>
    <p>Say I’m contracted by a friend of mine to create a word-counting command line tool very similar to wc. He promised to pay me $200 for this work, and I promised him I’d deliver the product in two increments—an alpha and beta version. I promised him I’d release the alpha version on Saturday and the beta version on Sunday. He is going to pay me $100 after the first release and the rest after the second release.</p><p>I’ll write in C, and he will pay in cash.</p><p>The tool is very primitive, and it only took me a few minutes to write. Take a look at it:</p>
    <pre>#include <stdio.h> #include <unistd.h> int main() { char ch; int count = 0; while (1) { if (read(STDIN_FILENO, &ch, 1) <= 0) { break; } if (ch == ' ') { ++count; } } if (count > 0) { ++count; } printf("%d\n", count); return 0; }</pre>
    <p>But let’s be professional and not forget about build automation and unit testing. Here is a simple Makefile that does them both:</p>
    <pre>all: wc test wc: wc.c gcc -o wc wc.c test: wc echo '' | ./wc | grep '0' echo 'Hello, world! How are you?' | ./wc | grep '5'</pre>
    <p>Now I run make from a command line and get this output:</p>
    <pre>$ make echo '' | ./wc | grep '0' 0 echo 'Hello, world! How are you?' | ./wc | grep '5' 5</pre>
    <p>All clean!</p><p>I’m ready to get my $200. Wait, the deal was to deliver two versions and get cash in two installments. Let’s back up a little and think—how can we break this small tool into two parts?</p><p>On first thought, let’s release the tool itself first and build automation and testing next. Is that a good idea? Can we deliver any software without running it first with a test? How can I be sure that it works if I don’t ship tests together with it? What will my friend think about me releasing anything without tests? This would be a total embarrassment.</p><p>Okay, let’s release Makefile first and wc.c next. But what will my friend do with a couple of tests and no product in hand? This first release will be absolutely pointless, and I won’t get my $100.</p><aside class="quote">Every new increment must add some value to the product as it is perceived by the customer, not by us programmers</aside><p>Now we’re getting to the point of this article. What I’m trying to say is that every new increment must add some value to the product as it is perceived by the customer, not by us programmers. The Makefile is definitely a valuable artifact, but it provides no value to my friend. He doesn’t need it, but I need it.</p><p>Here is what I’m going to do. I’ll release a skeleton of the tool, backed by the tests but with an absolutely dummy implementation. Look at it:</p>
    <pre>#include <stdio.h> int main() { printf("5\n"); return 0; }</pre>
    <p>And I will modify the Makefile accordingly. I will disable the first test to make sure the build passes.</p><p>Does my tool work? Yes, it does. Does it count words? Yes, it does for some inputs. Does it have value to my friend. Obviously! He can run it from the command line, and he can pass a file as an input. He will always get number “5” as a result of counting, though. That’s a bummer, but it’s an alpha version. He doesn’t expect it to work perfectly.</p><p>However, it works, it is backed by tests, and it is properly packaged.</p><p>What I just did is a top-down approach to design. First of all, I created something that provides value to my customer. I made sure it also satisfies my technical objectives, like proper unit test coverage and build automation. But the most important goal for me was to make sure my friend received something … and paid me.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>First, no matter what the methodology is, we all write software for our users (a.k.a. customers, project sponsors, end users, or clients). Second, no matter what the methodology is, we write incrementally, releasing features and bug fixes one by one. Maybe I’m saying something absolutely obvious here, but it’s important to remember that each new version should first of all satisfy the needs of the user, not of us programmers. In other words, the way we decompose a big task into smaller pieces should be user-targeted, and that’s why you always work top down. Let’s see what I mean through a practical example.</p>
    Delicatessen (1991) by Jean-Pierre Jeunet<figcaption id="077c7d62">Delicatessen (1991) by Jean-Pierre Jeunet</figcaption>
    <p>Say I’m contracted by a friend of mine to create a word-counting command line tool very similar to wc. He promised to pay me $200 for this work, and I promised him I’d deliver the product in two increments—an alpha and beta version. I promised him I’d release the alpha version on Saturday and the beta version on Sunday. He is going to pay me $100 after the first release and the rest after the second release.</p><p>I’ll write in C, and he will pay in cash.</p><p>The tool is very primitive, and it only took me a few minutes to write. Take a look at it:</p>
    <pre>#include <stdio.h> #include <unistd.h> int main() { char ch; int count = 0; while (1) { if (read(STDIN_FILENO, &ch, 1) <= 0) { break; } if (ch == ' ') { ++count; } } if (count > 0) { ++count; } printf("%d\n", count); return 0; }</pre>
    <p>But let’s be professional and not forget about build automation and unit testing. Here is a simple Makefile that does them both:</p>
    <pre>all: wc test wc: wc.c gcc -o wc wc.c test: wc echo '' | ./wc | grep '0' echo 'Hello, world! How are you?' | ./wc | grep '5'</pre>
    <p>Now I run make from a command line and get this output:</p>
    <pre>$ make echo '' | ./wc | grep '0' 0 echo 'Hello, world! How are you?' | ./wc | grep '5' 5</pre>
    <p>All clean!</p><p>I’m ready to get my $200. Wait, the deal was to deliver two versions and get cash in two installments. Let’s back up a little and think—how can we break this small tool into two parts?</p><p>On first thought, let’s release the tool itself first and build automation and testing next. Is that a good idea? Can we deliver any software without running it first with a test? How can I be sure that it works if I don’t ship tests together with it? What will my friend think about me releasing anything without tests? This would be a total embarrassment.</p><p>Okay, let’s release Makefile first and wc.c next. But what will my friend do with a couple of tests and no product in hand? This first release will be absolutely pointless, and I won’t get my $100.</p><aside class="quote">Every new increment must add some value to the product as it is perceived by the customer, not by us programmers</aside><p>Now we’re getting to the point of this article. What I’m trying to say is that every new increment must add some value to the product as it is perceived by the customer, not by us programmers. The Makefile is definitely a valuable artifact, but it provides no value to my friend. He doesn’t need it, but I need it.</p><p>Here is what I’m going to do. I’ll release a skeleton of the tool, backed by the tests but with an absolutely dummy implementation. Look at it:</p>
    <pre>#include <stdio.h> int main() { printf("5\n"); return 0; }</pre>
    <p>And I will modify the Makefile accordingly. I will disable the first test to make sure the build passes.</p><p>Does my tool work? Yes, it does. Does it count words? Yes, it does for some inputs. Does it have value to my friend. Obviously! He can run it from the command line, and he can pass a file as an input. He will always get number “5” as a result of counting, though. That’s a bummer, but it’s an alpha version. He doesn’t expect it to work perfectly.</p><p>However, it works, it is backed by tests, and it is properly packaged.</p><p>What I just did is a top-down approach to design. First of all, I created something that provides value to my customer. I made sure it also satisfies my technical objectives, like proper unit test coverage and build automation. But the most important goal for me was to make sure my friend received something … and paid me.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Don't Repeat Yourself in Maven POMs; Use Jcabi-Parent </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/02/05/jcabi-parent-maven-pom.html>12 Best</li> <li /2015/02/05/jcabi-parent-maven-pom.html>All 292</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Webinars</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Talks</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Books</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Papers</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Pets</li> <li /2015/02/05/jcabi-parent-maven-pom.html class=”highlighted”>Trainings</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Award</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Testimonials</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Shift-M</li> <li /2015/02/05/jcabi-parent-maven-pom.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Don’t Repeat Yourself in Maven POMs; Use Jcabi-Parent</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
    badge
    <p>Maven is a build automation tool mostly for Java projects. It’s a great tool, but it has one important drawback that has motivated the creation of similar tools, like Gradle and SBT. That weakness is its verbosity of configuration. Maven gets all project build parameters from pom.xml, an XML file that can get very long. I’ve seen POM files of 3,000-plus lines. Taking into account 1) recent DSL buzz and 2) fear of XML, it’s only logical that many people don’t like Maven because of its pom.xml verbosity.</p><p>But even if you’re an XML fan who enjoys its strictness and elegance (like myself), you won’t like the necessity to repeat yourself in pom.xml for every project. If you’re working on multiple projects, code duplication will be enormous. An average Java web app uses a few dozen standard Maven plugins and almost the same number of pretty common dependencies, like JUnit, Apache Commons, Log4J, Mockito, etc. All of them have their versions and configurations, which have to be specified if you want to keep the project stable and avoid Maven warnings. Thus, once a new version of a plugin is released, you have to go through all pom.xml files in the projects you’re working on and update it there. You obviously understand what code duplication means. It’s a disaster. However, there is a solution.</p><p>jcabi-parent is a very simple Maven dependency with nothing inside it except a large pom.xml with multiple pre-configured dependencies, profiles, and plugins. All you need to do in order to reuse them all in your project is define com.jcabi:parent as your parent POM:</p>
    <pre><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.jcabi</groupId> <artifactId>parent</artifactId> <!-- check the latest version at http://parent.jcabi.com --> <version>0.32.1</version> </parent> [...] </project></pre>
    <p>That’s all you need. Now you can remove most of your custom configurations from pom.xml and rely on defaults provided by jcabi-parent. Its pom.xml is rather large and properly configured. Multiple projects depend on it, so you can be confident that you’re using the best possible configuration of all standard plugins.</p><p>Here are a few examples of pom.xml from projects that are using jcabi-parent (you can see how compact they are): Xembly ReXSL jcabi-http Qulice</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
    badge
    <p>Maven is a build automation tool mostly for Java projects. It’s a great tool, but it has one important drawback that has motivated the creation of similar tools, like Gradle and SBT. That weakness is its verbosity of configuration. Maven gets all project build parameters from pom.xml, an XML file that can get very long. I’ve seen POM files of 3,000-plus lines. Taking into account 1) recent DSL buzz and 2) fear of XML, it’s only logical that many people don’t like Maven because of its pom.xml verbosity.</p><p>But even if you’re an XML fan who enjoys its strictness and elegance (like myself), you won’t like the necessity to repeat yourself in pom.xml for every project. If you’re working on multiple projects, code duplication will be enormous. An average Java web app uses a few dozen standard Maven plugins and almost the same number of pretty common dependencies, like JUnit, Apache Commons, Log4J, Mockito, etc. All of them have their versions and configurations, which have to be specified if you want to keep the project stable and avoid Maven warnings. Thus, once a new version of a plugin is released, you have to go through all pom.xml files in the projects you’re working on and update it there. You obviously understand what code duplication means. It’s a disaster. However, there is a solution.</p><p>jcabi-parent is a very simple Maven dependency with nothing inside it except a large pom.xml with multiple pre-configured dependencies, profiles, and plugins. All you need to do in order to reuse them all in your project is define com.jcabi:parent as your parent POM:</p>
    <pre><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.jcabi</groupId> <artifactId>parent</artifactId> <!-- check the latest version at http://parent.jcabi.com --> <version>0.32.1</version> </parent> [...] </project></pre>
    <p>That’s all you need. Now you can remove most of your custom configurations from pom.xml and rely on defaults provided by jcabi-parent. Its pom.xml is rather large and properly configured. Multiple projects depend on it, so you can be confident that you’re using the best possible configuration of all standard plugins.</p><p>Here are a few examples of pom.xml from projects that are using jcabi-parent (you can see how compact they are): Xembly ReXSL jcabi-http Qulice</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> XSL Transformation in Java: An Easy Way </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/02/02/xsl-transformations-in-java.html>12 Best</li> <li /2015/02/02/xsl-transformations-in-java.html>All 292</li> <li /2015/02/02/xsl-transformations-in-java.html>Webinars</li> <li /2015/02/02/xsl-transformations-in-java.html>Talks</li> <li /2015/02/02/xsl-transformations-in-java.html>Books</li> <li /2015/02/02/xsl-transformations-in-java.html>Papers</li> <li /2015/02/02/xsl-transformations-in-java.html>Pets</li> <li /2015/02/02/xsl-transformations-in-java.html class=”highlighted”>Trainings</li> <li /2015/02/02/xsl-transformations-in-java.html>Award</li> <li /2015/02/02/xsl-transformations-in-java.html>Testimonials</li> <li /2015/02/02/xsl-transformations-in-java.html>Shift-M</li> <li /2015/02/02/xsl-transformations-in-java.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">XSL Transformation in Java: An Easy Way</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
    badge
    <p>XSL transformation (XSLT) is a powerful mechanism for converting one XML document into another. However, in Java, XML manipulations are rather verbose and complex. Even for a simple XSL transformation, you have to write a few dozen lines of code—and maybe even more than that if proper exception handling and logging is needed. jcabi-xml is a small open source library that makes life much easier by enabling XML parsing and XPath traversing with a few simple methods. Let’s see how this library helps in XSL transformations.</p><p>First, take a look at a practical example—rultor.com—a hosted DevOps assistant that automates release, merge, and deploy operations. Rultor keeps each conversation session with an end user (a.k.a. “talk”) in a DynamoDB record. There are multiple situations to handle in each talk; that’s why using multiple columns of a record is not really feasible. Instead, we’re keeping only a few parameters of each talk in record columns (like ID and name) and putting all the rest in a single XML column.</p><p>This is approximately how our DynamoDB table looks:</p>
    <pre>+----+---------------+--------------------------------------+ | id | name | xml | +----+---------------+--------------------------------------+ | 12 | jcabi-xml#54 | <?xml version='1.0'?> | | | | <talk public="true"> | | | | <request id="e5f4b3">...</request> | | | | </talk> | +----+---------------+--------------------------------------+ | 13 | jcabi-email#2 | <?xml version='1.0'?> | | | | <talk public="true"> | | | | <daemon id="f787fe">...</daemon> | | | | </talk> | +----+---------------+--------------------------------------+</pre>
    <p>Once a user posts @rultor status into a GitHub ticket, Rultor has to answer with a full status report about the current talk. In order to create such a text answer (a regular user would not appreciate an XML response), we have to fetch that xml column from the necessary DynamoDB record and convert it to plain English text.</p><p>Here is how we’re doing that with the help of jcabi-xml and its class, XSLDocument.</p>
    <pre>final String xml = // comes from DynamoDB final XSL xsl = new XSLDocument( this.getClass().getResourceAsStream("status.xsl") ); final String text = xsl.applyTo(xml);</pre>
    <p>That’s it. Now let’s see what’s there in that status.xsl file (this is just a skeleton of it; the full version is here):</p>
    <pre><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"> <xsl:output method="text"/> <xsl:template match="/talk"> <xsl:text>Hi, here is your status report:</xsl:text> ... </xsl:template> <xsl:template match="node()|@*"> <xsl:copy> <xsl:apply-templates select="node()|@*"/> </xsl:copy> </xsl:template> </xsl:stylesheet></pre>
    <p>It is good practice to create XSL documents only once per application run. We have a static utility method XSLDocument.make() for this:</p>
    <pre>final class Foo { private static final XSL STYLESHEET = XSLDocument.make( Foo.class.getResourceAsStream("stylesheet.xsl") ); public XML style(final XML xml) { return Foo.STYLESHEET.transform(xml); } }</pre>
    <p>Pay attention to the fact we’re using XSLT 2.0. Built-in Java implementation of XSLT doesn’t support version 2.0, and in order to make it work, we’re using these two Maven Saxon dependencies:</p>
    <pre><dependency> <groupId>net.sourceforge.saxon</groupId> <artifactId>saxon</artifactId> <version>9.1.0.8</version> <scope>runtime</scope> </dependency> <dependency> <groupId>net.sourceforge.saxon</groupId> <artifactId>saxon</artifactId> <version>9.1.0.8</version> <classifier>xpath</classifier> <scope>runtime</scope> </dependency></pre>
    <p>All you need to do to start using jcabi-xml for XSL transformations is add this dependency to your pom.xml:</p>
    <pre><dependency> <groupId>com.jcabi</groupId> <artifactId>jcabi-xml</artifactId> </dependency></pre>
    <p>If you have any problems or suggestions, don’t hesitate to submit an issue to the GitHub issue tracker.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
    badge
    <p>XSL transformation (XSLT) is a powerful mechanism for converting one XML document into another. However, in Java, XML manipulations are rather verbose and complex. Even for a simple XSL transformation, you have to write a few dozen lines of code—and maybe even more than that if proper exception handling and logging is needed. jcabi-xml is a small open source library that makes life much easier by enabling XML parsing and XPath traversing with a few simple methods. Let’s see how this library helps in XSL transformations.</p><p>First, take a look at a practical example—rultor.com—a hosted DevOps assistant that automates release, merge, and deploy operations. Rultor keeps each conversation session with an end user (a.k.a. “talk”) in a DynamoDB record. There are multiple situations to handle in each talk; that’s why using multiple columns of a record is not really feasible. Instead, we’re keeping only a few parameters of each talk in record columns (like ID and name) and putting all the rest in a single XML column.</p><p>This is approximately how our DynamoDB table looks:</p>
    <pre>+----+---------------+--------------------------------------+ | id | name | xml | +----+---------------+--------------------------------------+ | 12 | jcabi-xml#54 | <?xml version='1.0'?> | | | | <talk public="true"> | | | | <request id="e5f4b3">...</request> | | | | </talk> | +----+---------------+--------------------------------------+ | 13 | jcabi-email#2 | <?xml version='1.0'?> | | | | <talk public="true"> | | | | <daemon id="f787fe">...</daemon> | | | | </talk> | +----+---------------+--------------------------------------+</pre>
    <p>Once a user posts @rultor status into a GitHub ticket, Rultor has to answer with a full status report about the current talk. In order to create such a text answer (a regular user would not appreciate an XML response), we have to fetch that xml column from the necessary DynamoDB record and convert it to plain English text.</p><p>Here is how we’re doing that with the help of jcabi-xml and its class, XSLDocument.</p>
    <pre>final String xml = // comes from DynamoDB final XSL xsl = new XSLDocument( this.getClass().getResourceAsStream("status.xsl") ); final String text = xsl.applyTo(xml);</pre>
    <p>That’s it. Now let’s see what’s there in that status.xsl file (this is just a skeleton of it; the full version is here):</p>
    <pre><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"> <xsl:output method="text"/> <xsl:template match="/talk"> <xsl:text>Hi, here is your status report:</xsl:text> ... </xsl:template> <xsl:template match="node()|@*"> <xsl:copy> <xsl:apply-templates select="node()|@*"/> </xsl:copy> </xsl:template> </xsl:stylesheet></pre>
    <p>It is good practice to create XSL documents only once per application run. We have a static utility method XSLDocument.make() for this:</p>
    <pre>final class Foo { private static final XSL STYLESHEET = XSLDocument.make( Foo.class.getResourceAsStream("stylesheet.xsl") ); public XML style(final XML xml) { return Foo.STYLESHEET.transform(xml); } }</pre>
    <p>Pay attention to the fact we’re using XSLT 2.0. Built-in Java implementation of XSLT doesn’t support version 2.0, and in order to make it work, we’re using these two Maven Saxon dependencies:</p>
    <pre><dependency> <groupId>net.sourceforge.saxon</groupId> <artifactId>saxon</artifactId> <version>9.1.0.8</version> <scope>runtime</scope> </dependency> <dependency> <groupId>net.sourceforge.saxon</groupId> <artifactId>saxon</artifactId> <version>9.1.0.8</version> <classifier>xpath</classifier> <scope>runtime</scope> </dependency></pre>
    <p>All you need to do to start using jcabi-xml for XSL transformations is add this dependency to your pom.xml:</p>
    <pre><dependency> <groupId>com.jcabi</groupId> <artifactId>jcabi-xml</artifactId> </dependency></pre>
    <p>If you have any problems or suggestions, don’t hesitate to submit an issue to the GitHub issue tracker.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Making Your Boss Happy Is a False Objective </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/01/26/happy-boss-false-objective.html>12 Best</li> <li /2015/01/26/happy-boss-false-objective.html>All 292</li> <li /2015/01/26/happy-boss-false-objective.html>Webinars</li> <li /2015/01/26/happy-boss-false-objective.html>Talks</li> <li /2015/01/26/happy-boss-false-objective.html>Books</li> <li /2015/01/26/happy-boss-false-objective.html>Papers</li> <li /2015/01/26/happy-boss-false-objective.html>Pets</li> <li /2015/01/26/happy-boss-false-objective.html class=”highlighted”>Trainings</li> <li /2015/01/26/happy-boss-false-objective.html>Award</li> <li /2015/01/26/happy-boss-false-objective.html>Testimonials</li> <li /2015/01/26/happy-boss-false-objective.html>Shift-M</li> <li /2015/01/26/happy-boss-false-objective.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Making Your Boss Happy Is a False Objective</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>We all have bosses. We also have customers who pay us for running their software projects. They are my bosses for the time of the contract. I’m also acting as a boss for developers who are working for Zerocracy. It is obvious that a good employee/contractor is one who makes his boss/customer happy. But only a bad employee works toward this goal. Trying to make your boss happy is a false target that, if pursued, ruins the project. A professional employee works for the project, not for the boss.</p>
    The Million Dollar Hotel (2000) by Wim Wenders<figcaption id="a14f03e8">The Million Dollar Hotel (2000) by Wim Wenders</figcaption>
    <p>We all work on projects as developers, designers, programmers, managers, testers, you name it. The boss is also a member of the project. More formally, he or she is a stakeholder, same as every one of us. Each stakeholder has his own needs for the project: 1) Jeff, the developer, wants to learn Scala and collect his paychecks every two weeks; 2) Sally, the product owner, wants to attend an expo in Paris and also collect her paychecks; 3) Bob, the CTO, wants to raise round A funding and collect a big paycheck; etc.</p><p>The project has its own objectives, to achieve 1 million downloads in less than six months and under $300,000, for example. This is what the project works for. This is what all of us are here for.</p><p>Our personal needs may be fully satisfied while we’re all working toward this goal, or some of them may be sacrificed. I mean all of us, including the boss, whoever he or she is, either a CTO, a co-founder, a project manager, or a team lead.</p><p>The project is the source of our checks. Not the CFO.</p><aside class="quote">A true professional team player feels himself equal to all other members of the project, no matter how high they are in the hierarchy.</aside><p>The CFO is a stakeholder, like everyone else. The project gives him more power than others because it’s necessary for the whole mechanism to work properly. Every project member has his or her own roles and responsibilities. I write code; the CFO writes checks. I eat at McDonald’s; he drives a Jaguar. We have different needs, and we both agreed that the project would satisfy them. Otherwise we wouldn’t be here, right?</p><p>We’re all parts of a mechanism called a “project,” which works according to the rules and principles of project management whether we are aware of them or not. Whether we have a project manager or not. Even if we violate all of them and manage ourselves in total chaos, we still have a scope, cost, schedule, and all other attributes of project management.</p><p>A professional and savvy boss understands that his role in the mechanism is to clearly define project objectives and make sure everybody’s needs are aligned with those objectives. In a properly managed and organized project, everybody sees and feels how his or her personal needs are satisfied when the project achieves its objectives: Jeff learns Scala, Sally sees Paris, and Bob buys a new house.</p><p>However, if Jeff wants to learn Scala and we’re developing an iOS application, that is a problem for the boss to resolve. Either convince Jeff to fall in love with Swift (I doubt that’s possible) or replace him with someone who is already in love with it. It’s clear that a professional boss will resort to such a tragic act as firing Jeff not because of his personal feelings towards Jeff but because they are both working toward the project objectives. Jeff and the boss will both understand that Jeff’s need to learn Scala is not aligned with the objective of the project.</p><p>It is the CTO’s responsibility to do something about Jeff when his personal needs become misaligned with the objectives of the project that is paying his salary. A professional CEO understands that and always acts in the best interest of the project, not of himself or anyone else personally.</p><p>I believe a professional team player does two things: obeys and resists.</p><p>First, you have to understand that the boss is here in order to help you organize your time, your tasks, your communications, your plans, etc. He knows more about the project and uses that information to help you do your job. Your real boss is the project; the boss you interact with is just a hired manager who translates project objectives into plans, instructions, schedules, etc.</p><aside class="quote">Being a professional team player requires a constant readiness to resist each and every instruction.</aside><p>This boss is your colleague who does management while you’re writing code. You’re both equal. You and he are in the same boat. Your functions are different than his; that’s all. You’re not working for him but with him on a project. A true professional team player feels himself equal to all other members of the project, no matter how high they are in the hierarchy.</p><p>At the same time, he strictly follows the process and obeys all project rules and instructions, not because he is afraid of being fired but because he wants the project to succeed.</p><p>Second, being a professional team player requires a constant readiness to resist each and every instruction if you feel it contradicts the project objectives. A true professional doesn’t work for a boss. He doesn’t want to make the boss happy. He actually doesn’t care whether the boss is happy or not. He knows that the real boss is the project and tries to make the project successful and … happy.</p><p>A true professional always works for himself. Jeff wants to learn Scala and earn a certain amount of cash. He joined the project in order to satisfy these needs. If the project fails, Jeff won’t get the money and won’t fully learn Scala. So if the boss tells Jeff to do something that may jeopardize the project’s success, will Jeff do it? Does he care about disappointing the boss? Absolutely not. All he cares about is the project’s success, which translates to his personal success.</p><p>Thus, making your boss happy is a goal for the immature, fearsome, lazy, and weak. Making your project successful is an objective for professional, strong, mature, and brave team players.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>We all have bosses. We also have customers who pay us for running their software projects. They are my bosses for the time of the contract. I’m also acting as a boss for developers who are working for Zerocracy. It is obvious that a good employee/contractor is one who makes his boss/customer happy. But only a bad employee works toward this goal. Trying to make your boss happy is a false target that, if pursued, ruins the project. A professional employee works for the project, not for the boss.</p>
    The Million Dollar Hotel (2000) by Wim Wenders<figcaption id="a14f03e8">The Million Dollar Hotel (2000) by Wim Wenders</figcaption>
    <p>We all work on projects as developers, designers, programmers, managers, testers, you name it. The boss is also a member of the project. More formally, he or she is a stakeholder, same as every one of us. Each stakeholder has his own needs for the project: 1) Jeff, the developer, wants to learn Scala and collect his paychecks every two weeks; 2) Sally, the product owner, wants to attend an expo in Paris and also collect her paychecks; 3) Bob, the CTO, wants to raise round A funding and collect a big paycheck; etc.</p><p>The project has its own objectives, to achieve 1 million downloads in less than six months and under $300,000, for example. This is what the project works for. This is what all of us are here for.</p><p>Our personal needs may be fully satisfied while we’re all working toward this goal, or some of them may be sacrificed. I mean all of us, including the boss, whoever he or she is, either a CTO, a co-founder, a project manager, or a team lead.</p><p>The project is the source of our checks. Not the CFO.</p><aside class="quote">A true professional team player feels himself equal to all other members of the project, no matter how high they are in the hierarchy.</aside><p>The CFO is a stakeholder, like everyone else. The project gives him more power than others because it’s necessary for the whole mechanism to work properly. Every project member has his or her own roles and responsibilities. I write code; the CFO writes checks. I eat at McDonald’s; he drives a Jaguar. We have different needs, and we both agreed that the project would satisfy them. Otherwise we wouldn’t be here, right?</p><p>We’re all parts of a mechanism called a “project,” which works according to the rules and principles of project management whether we are aware of them or not. Whether we have a project manager or not. Even if we violate all of them and manage ourselves in total chaos, we still have a scope, cost, schedule, and all other attributes of project management.</p><p>A professional and savvy boss understands that his role in the mechanism is to clearly define project objectives and make sure everybody’s needs are aligned with those objectives. In a properly managed and organized project, everybody sees and feels how his or her personal needs are satisfied when the project achieves its objectives: Jeff learns Scala, Sally sees Paris, and Bob buys a new house.</p><p>However, if Jeff wants to learn Scala and we’re developing an iOS application, that is a problem for the boss to resolve. Either convince Jeff to fall in love with Swift (I doubt that’s possible) or replace him with someone who is already in love with it. It’s clear that a professional boss will resort to such a tragic act as firing Jeff not because of his personal feelings towards Jeff but because they are both working toward the project objectives. Jeff and the boss will both understand that Jeff’s need to learn Scala is not aligned with the objective of the project.</p><p>It is the CTO’s responsibility to do something about Jeff when his personal needs become misaligned with the objectives of the project that is paying his salary. A professional CEO understands that and always acts in the best interest of the project, not of himself or anyone else personally.</p><p>I believe a professional team player does two things: obeys and resists.</p><p>First, you have to understand that the boss is here in order to help you organize your time, your tasks, your communications, your plans, etc. He knows more about the project and uses that information to help you do your job. Your real boss is the project; the boss you interact with is just a hired manager who translates project objectives into plans, instructions, schedules, etc.</p><aside class="quote">Being a professional team player requires a constant readiness to resist each and every instruction.</aside><p>This boss is your colleague who does management while you’re writing code. You’re both equal. You and he are in the same boat. Your functions are different than his; that’s all. You’re not working for him but with him on a project. A true professional team player feels himself equal to all other members of the project, no matter how high they are in the hierarchy.</p><p>At the same time, he strictly follows the process and obeys all project rules and instructions, not because he is afraid of being fired but because he wants the project to succeed.</p><p>Second, being a professional team player requires a constant readiness to resist each and every instruction if you feel it contradicts the project objectives. A true professional doesn’t work for a boss. He doesn’t want to make the boss happy. He actually doesn’t care whether the boss is happy or not. He knows that the real boss is the project and tries to make the project successful and … happy.</p><p>A true professional always works for himself. Jeff wants to learn Scala and earn a certain amount of cash. He joined the project in order to satisfy these needs. If the project fails, Jeff won’t get the money and won’t fully learn Scala. So if the boss tells Jeff to do something that may jeopardize the project’s success, will Jeff do it? Does he care about disappointing the boss? Absolutely not. All he cares about is the project’s success, which translates to his personal success.</p><p>Thus, making your boss happy is a goal for the immature, fearsome, lazy, and weak. Making your project successful is an objective for professional, strong, mature, and brave team players.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> If. Then. Throw. Else. WTF? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/01/21/if-then-throw-else.html>12 Best</li> <li /2015/01/21/if-then-throw-else.html>All 292</li> <li /2015/01/21/if-then-throw-else.html>Webinars</li> <li /2015/01/21/if-then-throw-else.html>Talks</li> <li /2015/01/21/if-then-throw-else.html>Books</li> <li /2015/01/21/if-then-throw-else.html>Papers</li> <li /2015/01/21/if-then-throw-else.html>Pets</li> <li /2015/01/21/if-then-throw-else.html class=”highlighted”>Trainings</li> <li /2015/01/21/if-then-throw-else.html>Award</li> <li /2015/01/21/if-then-throw-else.html>Testimonials</li> <li /2015/01/21/if-then-throw-else.html>Shift-M</li> <li /2015/01/21/if-then-throw-else.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">If. Then. Throw. Else. WTF?</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>This is the code I could never understand:</p>
    <pre>if (x < 0) { throw new Exception("X can't be negative"); } else { System.out.println("X is positive or zero"); }</pre>
    <p>I have been trying to find a proper metaphor to explain its incorrectness. Today I finally found it.</p><p>If-then-else is a forking mechanism of procedural programming. The CPU either goes to the left and then does something or goes to the right and does something else. Imagine yourself driving a car and seeing this sign:</p>
    The figure
    <p>It looks logical, doesn’t it? You can go in the left lane if you’re not driving a truck. Otherwise you should go in the right lane. Both lanes meet up in a while. No matter which one you choose, you will end up on the same road. This is what this code block does:</p>
    <pre>if (x < 0) { System.out.println("X is negative"); } else { System.out.println("X is positive or zero"); }</pre>
    <p>Now, try to imagine this sign:</p>
    The figure
    <p>It looks very strange to me, and you will never see this sign anywhere simply because a dead end means an end, a full stop, a finish. What is the point of drawing a lane after the dead end sign? There is no point.</p><p>This is how a proper sign would look:</p>
    The figure
    <p>This is how a proper code block would look:</p>
    <pre>if (x < 0) { throw new Exception("X can't be negative"); } System.out.println("X is positive or zero");</pre>
    <p>The same is true for loops. This is wrong:</p>
    <pre>for (int x : numbers) { if (x < 0) { continue; } else { System.out.println("found positive number"); } }</pre>
    <p>While this is right:</p>
    <pre>for (int x : numbers) { if (x < 0) { continue; } System.out.println("found positive number"); }</pre>
    <p>There is no road after the dead end! If you draw it, your code looks like this very funny snippet I found a few years ago reviewing sources written by some very well-paid developer in one very serious company:</p>
    <pre>if (x < 0) { throw new Exception("X is negative"); System.exit(1); }</pre>
    <p>Don’t do this.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>This is the code I could never understand:</p>
    <pre>if (x < 0) { throw new Exception("X can't be negative"); } else { System.out.println("X is positive or zero"); }</pre>
    <p>I have been trying to find a proper metaphor to explain its incorrectness. Today I finally found it.</p><p>If-then-else is a forking mechanism of procedural programming. The CPU either goes to the left and then does something or goes to the right and does something else. Imagine yourself driving a car and seeing this sign:</p>
    The figure
    <p>It looks logical, doesn’t it? You can go in the left lane if you’re not driving a truck. Otherwise you should go in the right lane. Both lanes meet up in a while. No matter which one you choose, you will end up on the same road. This is what this code block does:</p>
    <pre>if (x < 0) { System.out.println("X is negative"); } else { System.out.println("X is positive or zero"); }</pre>
    <p>Now, try to imagine this sign:</p>
    The figure
    <p>It looks very strange to me, and you will never see this sign anywhere simply because a dead end means an end, a full stop, a finish. What is the point of drawing a lane after the dead end sign? There is no point.</p><p>This is how a proper sign would look:</p>
    The figure
    <p>This is how a proper code block would look:</p>
    <pre>if (x < 0) { throw new Exception("X can't be negative"); } System.out.println("X is positive or zero");</pre>
    <p>The same is true for loops. This is wrong:</p>
    <pre>for (int x : numbers) { if (x < 0) { continue; } else { System.out.println("found positive number"); } }</pre>
    <p>While this is right:</p>
    <pre>for (int x : numbers) { if (x < 0) { continue; } System.out.println("found positive number"); }</pre>
    <p>There is no road after the dead end! If you draw it, your code looks like this very funny snippet I found a few years ago reviewing sources written by some very well-paid developer in one very serious company:</p>
    <pre>if (x < 0) { throw new Exception("X is negative"); System.exit(1); }</pre>
    <p>Don’t do this.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> How to Cut Corners and Stay Cool </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/01/15/how-to-cut-corners.html>12 Best</li> <li /2015/01/15/how-to-cut-corners.html>All 292</li> <li /2015/01/15/how-to-cut-corners.html>Webinars</li> <li /2015/01/15/how-to-cut-corners.html>Talks</li> <li /2015/01/15/how-to-cut-corners.html>Books</li> <li /2015/01/15/how-to-cut-corners.html>Papers</li> <li /2015/01/15/how-to-cut-corners.html>Pets</li> <li /2015/01/15/how-to-cut-corners.html class=”highlighted”>Trainings</li> <li /2015/01/15/how-to-cut-corners.html>Award</li> <li /2015/01/15/how-to-cut-corners.html>Testimonials</li> <li /2015/01/15/how-to-cut-corners.html>Shift-M</li> <li /2015/01/15/how-to-cut-corners.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">How to Cut Corners and Stay Cool</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Spanish</li> <li>add yours!</li></ul><p class="unprintable"><p>You have a task assigned to you, and you don’t like it. You are simply not in the mood. You don’t know how to fix that damn bug. You have no idea how that bloody module was designed, and you don’t know how it works. But you have to fix the issue, which was reported by someone who has no clue how this software works. You get frustrated and blame that stupid project manager and programmers who were fired two years ago. You spend hours just to find out how the code works. Then even more hours trying to fix it. In the end, you miss the deadline and everybody blames you. Been there, done that?</p>
    Regarding Henry (1991) by Mike Nichols<figcaption id="34ee5620">Regarding Henry (1991) by Mike Nichols</figcaption>
    <p>There is, however, an alternative approach that provides a professional exit from this situation. Here are some tips I recommend to my peers who code with me in Zerocracy projects. In a nutshell, I’m going to explain how you can cut corners and remain professional, 1) protecting your nerves, 2) optimizing your project’s expenses, and 3) increasing the quality of the source code.</p><aside class="youtube"> <div class="box"> YouTube video #b6r2W3P9vgY<div class="play"></div></div><div>Blame the Project; 16 April 2016.</div></aside><p>Here is a list of options you have, in order of preference. I would recommend you start with the first one on the list and proceed down when you have to.</p><h2 id="create-dependencies-blame-them-and-wait">Create Dependencies, Blame Them, and Wait</h2><p>This is the first and most preferable option. If you can’t figure out how to fix an issue or how to implement a new feature, it’s a fault of the project, not you. Even if you can’t figure it out because you don’t know anything about Ruby and they hired you to fix bugs in a Ruby on Rails code base—it’s their fault. Why did they hire you when you know nothing about Ruby?</p><p>So be positive; don’t blame yourself. If you don’t know how this damn code works, it’s a fault of the code, not you. Good code is easy to understand and maintain.</p>
    badge
    <p>Don’t try to eat spaghetti code; complain to the chef and ask him or her to cook something better (BTW, I love spaghetti).</p><p>How can you do that? Create dependencies—new bugs complaining about unclear design, lack of unit tests, absence of necessary classes, or whatever. Be creative and offensive—in a constructive and professional way, of course. Don’t get personal. No matter who cooked that spaghetti, you have nothing against him or her personally. You just want another dish, that’s all.</p><aside class="quote">If you don’t know how this damn code works, it’s a fault of the code, not you.</aside><p>Once you have those dependencies reported, explain in the main ticket that you can’t continue until all of them are resolved. You will legally stop working, and someone else will improve the code you need. Later, when all dependencies are resolved and the code looks better, try to get back to it again. If you still see issues, create new dependencies. Keep doing this until the code in front of you is clean and easy to fix.</p><p>Don’t be a hero—don’t rush into fixing the bad code you inherited. Think like a developer, not a hacker. Remember that your first and most important responsibility as a disciplined engineer is to help the project reveal maintainability issues. Who will fix them and how is the responsibility of a project manager. Your job is to reveal, not to hide. By being a hero and trying to fix everything in the scope of a single task, you’re not doing the project a favor—you’re concealing the problem(s).</p><p>Edit: Another good example of a dependency may be a question raised at, for example, StackOverflow or a user list of a third-party library. If you can’t find a solution yourself and the problem is outside of the scope of your project—submit a question to SO and put its link to the source code (in JavaDoc block, for example).</p><h2 id="demand-better-documentation-and-wait">Demand Better Documentation and Wait</h2><p>All dependencies are resolved and the code looks clean, but you still don’t understand how to fix the problem or implement a new feature. It’s too complex. Or maybe you just don’t know how this library works. Or you’ve never done anything like that before. Anyhow, you can’t continue because you don’t understand. And in order to understand, you will need a lot of time—much more than you have from your project manager or your Scrum board. What do you do?</p>
    badge
    <p>Again, think positively and don’t blame yourself. If the software is not clear enough for a total stranger, it’s “their” fault, not yours. They created the software in a way that’s difficult to digest and modify. But the code is clean; it’s not spaghetti anymore. It’s a perfectly cooked lobster, but you don’t know how to eat lobster! You’ve never ate it before.</p><p>The chef did a good job; he cooked it well, but the restaurant didn’t give you any instructions on how to eat such a sophisticated dish. What do you do?</p><p>You ask for a manual. You ask for documentation. Properly designed and written source code must be properly documented. Once you see that something is not clear for you, create new dependencies that ask for better documentation of certain aspects of the code.</p><p>Again, don’t be a hero and try to understand everything yourself. Of course you’re a smart guy, but the project doesn’t need a single smart guy. The project needs maintainable code that is easy to modify, even by someone who is not as smart as yourself. So do your project a favor: reveal the documentation issue, and ask someone to fix it for you. Not just for you, for everybody. The entire team will benefit from such a request. Once the documentation is fixed, you will continue with your task, and everybody will get source code that is a bit better than it was before. Win-win, isn’t it?</p><h2 id="reproduce-the-bug-and-call-it-a-day">Reproduce the Bug and Call It a Day</h2><p>Now the code is clean, the documentation is good enough, but you’re stuck anyway. What to do? Well, I’m a big fan of test-driven development, so my next suggestion would be to create a test that reproduces the bug. Basically, this is what you should start every ticket with, be it a bug or a feature. Catch the bug with a unit test! Prove that the bug exists by failing the build with a new test.</p>
    badge
    <p>This may be rather difficult to achieve, especially when the software you’re trying to fix or modify was written by idiots someone who had no idea about unit testing. There are plenty of techniques that may help you find a way to make such software more testable. I would highly recommend you read Working Effectively with Legacy Code by Michael Feathers. There are many different patterns, and most of them work.</p><aside class="quote">Catching a bug with a unit test is, in most cases, more than 80% of success.</aside><p>Once you manage to reproduce the bug and the build fails, stop right there. That’s more than enough for a single piece of work. Skip the test (for example, using @Ignore annotation in JUnit 4) and commit your changes. Then add documentation to the unit test you just created, preferably in the form of a @todo. Explain there that you managed to reproduce the problem but didn’t have enough time to fix it. Or maybe you just don’t know how to fix it. Be honest and give all possible details.</p><p>I believe that catching a bug with a unit test is, in most cases, more than 80% of success. The rest is way more simple: just fix the code and make the test pass. Leave this job to someone else.</p><h2 id="prove-a-bugs-absence">Prove a Bug’s Absence</h2><p>Very often you simply can’t reproduce a bug. That’s not because the code is not testable and can’t be used in a unit test but because you can’t reproduce an error situation. You know that the code crashes in production, but you can’t crash it in a test. The error stack trace reported by the end user or your production logging system is not reproducible. It’s a very common situation. What do you do?</p>
    badge
    <p>I think the best option here is to create a test that will prove that the code works as intended. The test won’t fail, and the build will remain clean. You will commit it to the repository and … report that the problem is solved. You will say that the reported bug doesn’t really exist in real life. You will state that there is no bug—“our software works correctly; here is the proof: see my new unit test.”</p><p>Will they believe you? I don’t think so, but they don’t have a choice. They can’t push you any further. You’ve already done something—created a new test that proves everything is fine. The ticket will be closed and the project will move on.</p><aside class="youtube"> <div class="box"> YouTube video #YBQoTZ-1X-o<div class="play"></div></div><div>How to Cut Corners and Stay Cool (webinar #15); 1 June 2016.</div></aside><p>If, later on, the same problem occurs in production, a new bug will be reported. It will be linked to your ticket. Your experience will help someone investigate the bug further. Maybe that guy will also fail to catch the bug with a test and will also create a new, successful and “useless” test. And this may happen again and again. Eventually, this cumulative group experience will help the last guy catch the bug and fix it.</p><p>Thus, a new passing test is a good response to a bug that you can’t catch with a unit test.</p><h2 id="disable-the-feature">Disable the Feature</h2><p>Sometimes the unit test technique won’t work, mostly because a bug will be too important to be ignored. They won’t agree with you when you show them a unit test that proves the bug doesn’t exist. They will tell you that “when our users are trying to download a PDF, they get a blank page.” And they will also say they don’t really care about your bloody unit tests. All they care about is that PDF document that should be downloadable. So the trick with a unit test won’t work. What do you do?</p><aside class="quote">Production errors are not programmers’ mistakes, though delayed tickets are.</aside><p>It depends on many factors, and most of these factors are not technical. They are political, organizational, managerial, social, you name it. However, in most cases, I would recommend you disable that toxic feature, release a new version, and close the ticket.</p><p>You will take the problem off your shoulders and everybody will be pleased. Well, except that poor end user. But this is not your problem. This is the fault of management, which didn’t organize pre-production testing properly. Again, don’t take this blame on yourself. Your job is to keep the code clean and finish your tickets in a reasonable amount of time. Their job is to make sure that developers, testers, DevOps, marketers, product managers, and designers work together to deliver the product with an acceptable number of errors.</p><p>Production errors are not programmers’ mistakes, though delayed tickets are. If you keep a ticket in your hands for too long, you become an unmanageable unit of work. They simply can’t manage you anymore. You’re doing something, trying to fix the bug, saying “I’m trying, I’m trying …” How can they manage such a guy? Instead, you should deliver quickly, even if it comes at the cost of a temporarily disabled feature.</p><h2 id="say-no">Say No</h2><p>OK, let’s say none of the above works. The code is clean, the documentation is acceptable, but you can’t catch the bug, and they don’t accept a unit test from you as proof of the bug’s absence. They also don’t allow you to disable a feature, because it is critical to the user experience. What choices do you have? Just one.</p>
    badge
    <p>Be professional and say “No, I can’t do this; find someone else.” Being a professional developer doesn’t mean being able to fix any problem. Instead, it means honesty. If you see that you can’t fix the problem, say so as soon as possible. Let them decide what to do. If they eventually decide to fire you because of that, you will remain a professional. They will remember you as a guy who was honest and took his reputation seriously. In the end, you will win.</p><p>Don’t hold the task in your hands. The minute you realize you’re not the best guy for it or you simply can’t fix it—notify your manager. Make it his problem. Actually, it is his problem in the first place. He hired you. He interviewed you. He decided to give you this task. He estimated your abilities and your skills. So it’s payback time.</p><aside class="quote">Being a professional developer doesn’t mean being able to fix any problem.</aside><p>Your “No!” will be very valuable feedback for him. It will help him make his next important management decisions.</p><p>On the other hand, if you lie just to give the impression you’re a guy who can fix anything and yet fail in the end, you will damage not only your reputation but also the project’s performance and objectives.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>You have a task assigned to you, and you don’t like it. You are simply not in the mood. You don’t know how to fix that damn bug. You have no idea how that bloody module was designed, and you don’t know how it works. But you have to fix the issue, which was reported by someone who has no clue how this software works. You get frustrated and blame that stupid project manager and programmers who were fired two years ago. You spend hours just to find out how the code works. Then even more hours trying to fix it. In the end, you miss the deadline and everybody blames you. Been there, done that?</p>
    Regarding Henry (1991) by Mike Nichols<figcaption id="34ee5620">Regarding Henry (1991) by Mike Nichols</figcaption>
    <p>There is, however, an alternative approach that provides a professional exit from this situation. Here are some tips I recommend to my peers who code with me in Zerocracy projects. In a nutshell, I’m going to explain how you can cut corners and remain professional, 1) protecting your nerves, 2) optimizing your project’s expenses, and 3) increasing the quality of the source code.</p><aside class="youtube"> <div class="box"> YouTube video #b6r2W3P9vgY<div class="play"></div></div><div>Blame the Project; 16 April 2016.</div></aside><p>Here is a list of options you have, in order of preference. I would recommend you start with the first one on the list and proceed down when you have to.</p><h2 id="create-dependencies-blame-them-and-wait">Create Dependencies, Blame Them, and Wait</h2><p>This is the first and most preferable option. If you can’t figure out how to fix an issue or how to implement a new feature, it’s a fault of the project, not you. Even if you can’t figure it out because you don’t know anything about Ruby and they hired you to fix bugs in a Ruby on Rails code base—it’s their fault. Why did they hire you when you know nothing about Ruby?</p><p>So be positive; don’t blame yourself. If you don’t know how this damn code works, it’s a fault of the code, not you. Good code is easy to understand and maintain.</p>
    badge
    <p>Don’t try to eat spaghetti code; complain to the chef and ask him or her to cook something better (BTW, I love spaghetti).</p><p>How can you do that? Create dependencies—new bugs complaining about unclear design, lack of unit tests, absence of necessary classes, or whatever. Be creative and offensive—in a constructive and professional way, of course. Don’t get personal. No matter who cooked that spaghetti, you have nothing against him or her personally. You just want another dish, that’s all.</p><aside class="quote">If you don’t know how this damn code works, it’s a fault of the code, not you.</aside><p>Once you have those dependencies reported, explain in the main ticket that you can’t continue until all of them are resolved. You will legally stop working, and someone else will improve the code you need. Later, when all dependencies are resolved and the code looks better, try to get back to it again. If you still see issues, create new dependencies. Keep doing this until the code in front of you is clean and easy to fix.</p><p>Don’t be a hero—don’t rush into fixing the bad code you inherited. Think like a developer, not a hacker. Remember that your first and most important responsibility as a disciplined engineer is to help the project reveal maintainability issues. Who will fix them and how is the responsibility of a project manager. Your job is to reveal, not to hide. By being a hero and trying to fix everything in the scope of a single task, you’re not doing the project a favor—you’re concealing the problem(s).</p><p>Edit: Another good example of a dependency may be a question raised at, for example, StackOverflow or a user list of a third-party library. If you can’t find a solution yourself and the problem is outside of the scope of your project—submit a question to SO and put its link to the source code (in JavaDoc block, for example).</p><h2 id="demand-better-documentation-and-wait">Demand Better Documentation and Wait</h2><p>All dependencies are resolved and the code looks clean, but you still don’t understand how to fix the problem or implement a new feature. It’s too complex. Or maybe you just don’t know how this library works. Or you’ve never done anything like that before. Anyhow, you can’t continue because you don’t understand. And in order to understand, you will need a lot of time—much more than you have from your project manager or your Scrum board. What do you do?</p>
    badge
    <p>Again, think positively and don’t blame yourself. If the software is not clear enough for a total stranger, it’s “their” fault, not yours. They created the software in a way that’s difficult to digest and modify. But the code is clean; it’s not spaghetti anymore. It’s a perfectly cooked lobster, but you don’t know how to eat lobster! You’ve never ate it before.</p><p>The chef did a good job; he cooked it well, but the restaurant didn’t give you any instructions on how to eat such a sophisticated dish. What do you do?</p><p>You ask for a manual. You ask for documentation. Properly designed and written source code must be properly documented. Once you see that something is not clear for you, create new dependencies that ask for better documentation of certain aspects of the code.</p><p>Again, don’t be a hero and try to understand everything yourself. Of course you’re a smart guy, but the project doesn’t need a single smart guy. The project needs maintainable code that is easy to modify, even by someone who is not as smart as yourself. So do your project a favor: reveal the documentation issue, and ask someone to fix it for you. Not just for you, for everybody. The entire team will benefit from such a request. Once the documentation is fixed, you will continue with your task, and everybody will get source code that is a bit better than it was before. Win-win, isn’t it?</p><h2 id="reproduce-the-bug-and-call-it-a-day">Reproduce the Bug and Call It a Day</h2><p>Now the code is clean, the documentation is good enough, but you’re stuck anyway. What to do? Well, I’m a big fan of test-driven development, so my next suggestion would be to create a test that reproduces the bug. Basically, this is what you should start every ticket with, be it a bug or a feature. Catch the bug with a unit test! Prove that the bug exists by failing the build with a new test.</p>
    badge
    <p>This may be rather difficult to achieve, especially when the software you’re trying to fix or modify was written by idiots someone who had no idea about unit testing. There are plenty of techniques that may help you find a way to make such software more testable. I would highly recommend you read Working Effectively with Legacy Code by Michael Feathers. There are many different patterns, and most of them work.</p><aside class="quote">Catching a bug with a unit test is, in most cases, more than 80% of success.</aside><p>Once you manage to reproduce the bug and the build fails, stop right there. That’s more than enough for a single piece of work. Skip the test (for example, using @Ignore annotation in JUnit 4) and commit your changes. Then add documentation to the unit test you just created, preferably in the form of a @todo. Explain there that you managed to reproduce the problem but didn’t have enough time to fix it. Or maybe you just don’t know how to fix it. Be honest and give all possible details.</p><p>I believe that catching a bug with a unit test is, in most cases, more than 80% of success. The rest is way more simple: just fix the code and make the test pass. Leave this job to someone else.</p><h2 id="prove-a-bugs-absence">Prove a Bug’s Absence</h2><p>Very often you simply can’t reproduce a bug. That’s not because the code is not testable and can’t be used in a unit test but because you can’t reproduce an error situation. You know that the code crashes in production, but you can’t crash it in a test. The error stack trace reported by the end user or your production logging system is not reproducible. It’s a very common situation. What do you do?</p>
    badge
    <p>I think the best option here is to create a test that will prove that the code works as intended. The test won’t fail, and the build will remain clean. You will commit it to the repository and … report that the problem is solved. You will say that the reported bug doesn’t really exist in real life. You will state that there is no bug—“our software works correctly; here is the proof: see my new unit test.”</p><p>Will they believe you? I don’t think so, but they don’t have a choice. They can’t push you any further. You’ve already done something—created a new test that proves everything is fine. The ticket will be closed and the project will move on.</p><aside class="youtube"> <div class="box"> YouTube video #YBQoTZ-1X-o<div class="play"></div></div><div>How to Cut Corners and Stay Cool (webinar #15); 1 June 2016.</div></aside><p>If, later on, the same problem occurs in production, a new bug will be reported. It will be linked to your ticket. Your experience will help someone investigate the bug further. Maybe that guy will also fail to catch the bug with a test and will also create a new, successful and “useless” test. And this may happen again and again. Eventually, this cumulative group experience will help the last guy catch the bug and fix it.</p><p>Thus, a new passing test is a good response to a bug that you can’t catch with a unit test.</p><h2 id="disable-the-feature">Disable the Feature</h2><p>Sometimes the unit test technique won’t work, mostly because a bug will be too important to be ignored. They won’t agree with you when you show them a unit test that proves the bug doesn’t exist. They will tell you that “when our users are trying to download a PDF, they get a blank page.” And they will also say they don’t really care about your bloody unit tests. All they care about is that PDF document that should be downloadable. So the trick with a unit test won’t work. What do you do?</p><aside class="quote">Production errors are not programmers’ mistakes, though delayed tickets are.</aside><p>It depends on many factors, and most of these factors are not technical. They are political, organizational, managerial, social, you name it. However, in most cases, I would recommend you disable that toxic feature, release a new version, and close the ticket.</p><p>You will take the problem off your shoulders and everybody will be pleased. Well, except that poor end user. But this is not your problem. This is the fault of management, which didn’t organize pre-production testing properly. Again, don’t take this blame on yourself. Your job is to keep the code clean and finish your tickets in a reasonable amount of time. Their job is to make sure that developers, testers, DevOps, marketers, product managers, and designers work together to deliver the product with an acceptable number of errors.</p><p>Production errors are not programmers’ mistakes, though delayed tickets are. If you keep a ticket in your hands for too long, you become an unmanageable unit of work. They simply can’t manage you anymore. You’re doing something, trying to fix the bug, saying “I’m trying, I’m trying …” How can they manage such a guy? Instead, you should deliver quickly, even if it comes at the cost of a temporarily disabled feature.</p><h2 id="say-no">Say No</h2><p>OK, let’s say none of the above works. The code is clean, the documentation is acceptable, but you can’t catch the bug, and they don’t accept a unit test from you as proof of the bug’s absence. They also don’t allow you to disable a feature, because it is critical to the user experience. What choices do you have? Just one.</p>
    badge
    <p>Be professional and say “No, I can’t do this; find someone else.” Being a professional developer doesn’t mean being able to fix any problem. Instead, it means honesty. If you see that you can’t fix the problem, say so as soon as possible. Let them decide what to do. If they eventually decide to fire you because of that, you will remain a professional. They will remember you as a guy who was honest and took his reputation seriously. In the end, you will win.</p><p>Don’t hold the task in your hands. The minute you realize you’re not the best guy for it or you simply can’t fix it—notify your manager. Make it his problem. Actually, it is his problem in the first place. He hired you. He interviewed you. He decided to give you this task. He estimated your abilities and your skills. So it’s payback time.</p><aside class="quote">Being a professional developer doesn’t mean being able to fix any problem.</aside><p>Your “No!” will be very valuable feedback for him. It will help him make his next important management decisions.</p><p>On the other hand, if you lie just to give the impression you’re a guy who can fix anything and yet fail in the end, you will damage not only your reputation but also the project’s performance and objectives.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> A Compound Name Is a Code Smell </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/01/12/compound-name-is-code-smell.html>12 Best</li> <li /2015/01/12/compound-name-is-code-smell.html>All 292</li> <li /2015/01/12/compound-name-is-code-smell.html>Webinars</li> <li /2015/01/12/compound-name-is-code-smell.html>Talks</li> <li /2015/01/12/compound-name-is-code-smell.html>Books</li> <li /2015/01/12/compound-name-is-code-smell.html>Papers</li> <li /2015/01/12/compound-name-is-code-smell.html>Pets</li> <li /2015/01/12/compound-name-is-code-smell.html class=”highlighted”>Trainings</li> <li /2015/01/12/compound-name-is-code-smell.html>Award</li> <li /2015/01/12/compound-name-is-code-smell.html>Testimonials</li> <li /2015/01/12/compound-name-is-code-smell.html>Shift-M</li> <li /2015/01/12/compound-name-is-code-smell.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">A Compound Name Is a Code Smell</h1><aside class='book'>book coverRead more about this subject in Section 5.1
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Chinese</li> <li>add yours!</li></ul><p class="unprintable"><p>Do you name variables like textLength, table_name, or current-user-email? All three are compound names that consist of more than one word. Even though they look more descriptive than name, length, or email, I would strongly recommend avoiding them. I believe a variable name that is more complex than a noun is a code smell. Why? Because we usually give a variable a compound name when its scope is so big and complex that a simple noun would sound ambiguous. And a big, complex scope is an obvious code smell.</p>
    The Meaning of Life (1983) by Terry Jones and Terry Gilliam<figcaption id="6b72f309">The Meaning of Life (1983) by Terry Jones and Terry Gilliam</figcaption>
    <p>The scope of a variable is the place where it is visible, like a method, for example. Look at this Ruby class:</p>
    <pre>class CSV def initialize(csvFileName) @fileName = csvFileName end def readRecords() File.readLines(@fileName).map |csvLine| csvLine.split(',') end end end</pre>
    <p>The visible scope of variable csvFileName is method initialize(), which is a constructor of the class CSV. Why does it need a compound name that consists of three words? Isn’t it already clear that a single-argument constructor of class CSV expects the name of a file with comma-separated values? I would rename it to file.</p><p>Next, the scope of @fileName is the entire CSV class. Renaming a single variable in the class to just @file won’t introduce any confusion. It’s still clear what file we’re dealing with. The same situation exists with the csvLine variable. It is clear that we’re dealing with CSV lines here. The csv prefix is just a redundancy. Here is how I would refactor the class:</p>
    <pre>class CSV def initialize(file) @file = file end def records() File.readLines(@file).map |line| line.split(',') end end end</pre>
    <p>Now it looks clear and concise.</p><p>If you can’t perform such a refactoring, it means your scope is too big and/or too complex. An ideal method should deal with up to five variables, and an ideal class should encapsulate up to five properties.</p><p>If we have five variables, can’t we find five nouns to name them?</p><p>Adam and Eve didn’t have second names. They were unique in Eden, as were many other characters in the Old Testament. Second and middle names were invented later in order to resolve ambiguity. To keep your methods and classes clean and solid, and to prevent ambiguity, try to give your variables and methods unique single-word names, just like Adam and Eve were named by you know who :)</p><p>PS. Also, redundant variables are evil as well.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Do you name variables like textLength, table_name, or current-user-email? All three are compound names that consist of more than one word. Even though they look more descriptive than name, length, or email, I would strongly recommend avoiding them. I believe a variable name that is more complex than a noun is a code smell. Why? Because we usually give a variable a compound name when its scope is so big and complex that a simple noun would sound ambiguous. And a big, complex scope is an obvious code smell.</p>
    The Meaning of Life (1983) by Terry Jones and Terry Gilliam<figcaption id="6b72f309">The Meaning of Life (1983) by Terry Jones and Terry Gilliam</figcaption>
    <p>The scope of a variable is the place where it is visible, like a method, for example. Look at this Ruby class:</p>
    <pre>class CSV def initialize(csvFileName) @fileName = csvFileName end def readRecords() File.readLines(@fileName).map |csvLine| csvLine.split(',') end end end</pre>
    <p>The visible scope of variable csvFileName is method initialize(), which is a constructor of the class CSV. Why does it need a compound name that consists of three words? Isn’t it already clear that a single-argument constructor of class CSV expects the name of a file with comma-separated values? I would rename it to file.</p><p>Next, the scope of @fileName is the entire CSV class. Renaming a single variable in the class to just @file won’t introduce any confusion. It’s still clear what file we’re dealing with. The same situation exists with the csvLine variable. It is clear that we’re dealing with CSV lines here. The csv prefix is just a redundancy. Here is how I would refactor the class:</p>
    <pre>class CSV def initialize(file) @file = file end def records() File.readLines(@file).map |line| line.split(',') end end end</pre>
    <p>Now it looks clear and concise.</p><p>If you can’t perform such a refactoring, it means your scope is too big and/or too complex. An ideal method should deal with up to five variables, and an ideal class should encapsulate up to five properties.</p><p>If we have five variables, can’t we find five nouns to name them?</p><p>Adam and Eve didn’t have second names. They were unique in Eden, as were many other characters in the Old Testament. Second and middle names were invented later in order to resolve ambiguity. To keep your methods and classes clean and solid, and to prevent ambiguity, try to give your variables and methods unique single-word names, just like Adam and Eve were named by you know who :)</p><p>PS. Also, redundant variables are evil as well.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> How to Be Honest and Keep a Customer </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>12 Best</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>All 292</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Webinars</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Talks</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Books</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Papers</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Pets</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html class=”highlighted”>Trainings</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Award</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Testimonials</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Shift-M</li> <li /2015/01/05/how-to-be-honest-and-keep-customer.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">How to Be Honest and Keep a Customer</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>Most of our clients are rather surprised when we explain to them that they will have full access to the source code from the first day of the project. We let them see everything that is happening in the project, including the Git repository, bug reports, discussions between programmers, continuous integration fails, etc. They often tell me that other software development outsourcing teams keep this information in-house and deliver only final releases, rarely together with the source code.</p><p>I understand why other developers are trying to hide as much as possible. Giving a project sponsor full access to the development environment is not easy at all. Here is a summary of problems we’ve been having and our solutions. I hope they help you honestly show your clients all project internals and still keep them on board.</p>
    99 francs (2007) by Jan Kounen<figcaption id="822a28fd">99 francs (2007) by Jan Kounen</figcaption>
    <h2 id="he-is-breaking-our-process">He Is Breaking Our Process</h2><p>This is the most popular problem we face with our new clients. Once they gain access to the development environment, they try to give instructions directly to programmers, walking around our existing process. “I’m paying these guys; why can’t I tell them what to do?” is a very typical mindset. Instead of submitting requests through our standard change management mechanism, such a client goes directly to one of the programmers and tells him what should be fixed, how, and when. It’s micro-management in its worst form. We see it very often. What do we do?</p><aside class="quote">The simplest answer is that the client is a moron. Sometimes this is exactly the case, but it’s a rare one.</aside><p>First, we try to understand why it’s happening. The simplest answer is that the client is a moron. Sometimes this is exactly the case, but it’s a rare one. Much more often, our clients are not that bad. What is it, then? Why can’t they follow the process and abide by the rules? There are a few possible reasons.</p><p>Maybe the rules are not explained well. This is the most popular root cause—the rules of work are not clear enough for the client. He just doesn’t know what he is supposed to do in order to submit a request and get it implemented. To prevent this, we try to educate our clients at the beginning of a new project. We even write guidance manuals for clients. Most of them are happy to read them and learn the way we work, because they understand that this is the best way to achieve success while working with us.</p><aside class="youtube"> <div class="box"> YouTube video #Rip_04Bv3Jk<div class="play"></div></div><div>How to be Honest and Keep a Client?; 11 June 2017.</div></aside><p>Maybe our management is chaotic, and the client is trying to “organize” us by giving explicit instructions regarding the most important tasks. We’ve seen it before, and we are always trying to learn from this. As soon as we see that the client is trying to micro-manage us, we ask ourselves: “Is our process transparent enough? Do we give enough information to the client about milestones, risks, plans, costs, etc.?” In most cases, it’s our own fault, and we’re trying to learn and improve. If so, it’s important to react fast, before the client becomes too aggressive in his orders and instructions. It will be very difficult to escort him back to the normal process once he gets “micro-management” in his blood.</p><p>Maybe the client is not busy enough and has a lot of free time, which he is happy to spend by giving orders and distracting your team. I’ve seen this many times. A solution? Keep him busy. Turn him into a member of the team and assign him some tasks related to documentation and research. In my experience, most clients would be happy to do this work and help the project.</p><h2 id="he-is-asking-too-much">He Is Asking Too Much</h2><p>A technically-savvy client can turn the life of an architect into a nightmare by constantly asking him to explain every single technical decision made, from “Why PostgreSQL instead of MySQL?” to “Why doesn’t this method throw a checked exception?” Constantly answering such questions can turn a project into a school of programming. Even though he is paying for our time, that doesn’t mean we should teach him how to develop software, right? On the other hand, he is interested in knowing how his software is developed and how it works. It’s a fair request, isn’t it?</p><aside class="quote">He is interested in knowing how his software is developed and how it works. It’s a fair request, isn’t it?</aside><p>I believe there is a win-win solution to this problem. Here is how we manage it. First of all, we make all his requests formal. We ask a client to create a new ticket for each request, properly explaining what is not clear and how much detail is expected in the explanation.</p><p>Second, we look at such requests positively—they are good indicators of certain inconsistencies in the software. If it’s not clear for the client why PostgreSQL is used and not MySQL, it’s a fault of our architect. He didn’t document his decision and didn’t explain how it was made, what other options were considered, what selection criteria were applied, etc. Thus, a request from a client is a bug we get for free. So, we look at it positively.</p><p>Finally, we charge our clients for the answers given. Every question, submitted as a ticket, goes through the full flow and gets billed just as any other ticket. This approach prevents the client from asking for too much. He realizes that we’re ready to explain anything he wants, but he will pay for it.</p><h2 id="he-is-telling-too-much">He Is Telling Too Much</h2><p>This problem is even bigger than the previous one. Some clients believe they are savvy enough to argue with our architect and our programmers about how the software should be developed. They don’t just ask why PostgreSQL is used, they tell us that we should use MySQL, because “I know that it’s a great database; my friend is using it, and his business is growing!” Sometimes it gets even worse, when suggestions are directed at every class or even a method, like “You should use a Singleton pattern here!”</p><p>Our first choice is to agree and do what he wants. But it’s a road to nowhere. Once you do it, your project is ruined, and you should start thinking about a divorce with this client. Your entire team will quickly turn into a group of coding monkeys, micro-managed by someone with some cash. It’s a very wrong direction; don’t even think about going there.</p><p>The second choice is to tell the client to mind his own business and let us do ours. He hired us because we’re professional enough to develop the software according to his requirements. If he questions our capabilities, he is free to change the contractor. But until then, he has to trust our decisions. Will this work? I doubt it. It’s the same as giving him the finger. He will get offended, and you won’t get anything.</p><p>The solution here is to turn the client’s demands into project requirements. Most of them will be lost in the process, because they won’t be sane enough to form a good requirement. Others will be documented, estimated, and crossed-out by the client himself, because he will realize they are pointless or too expensive. Only a few of them will survive, since they will be reasonable enough. And they will help the project. So it is also a win-win solution.</p><aside class="quote">Never take a client’s demands directly to execution, but rather use them first to amend the requirements documentation.</aside><p>For example, he says that “you should use MySQL because it’s great.” You tell him that the project requirements document doesn’t limit you to choose whichever database you like. Should it? He says yes, of course! OK, let’s try to document such a requirement. How will it sound? How about, “We should only use great databases?” Sound correct? If so, then PostgreSQL satisfies this requirement. Problem solved; let us continue to do our work. He will have a hard time figuring out how to write a requirement in a way that disallows PostgreSQL but allows MySQL. It is simply not possible in most cases.</p><p>Sometimes, though, it will make sense; for example, “We should use a database server that understands our legacy data in MySQL format.” This is a perfectly sane requirement, and the only way to satisfy it is to use MySQL.</p><p>Thus, my recommendation is to never take a client’s demands directly to execution, but rather use them first to amend the requirements documentation. Even if you don’t have such documentation, create a simple one-page document. Agree with the client that you work against this document, and when anyone wants to change something, you first have to amend the document and then have your team ensure the software satisfies it. This kind of discipline will be accepted by any client and will protect you against sudden and distracting corrections.</p><h2 id="he-is-questioning-our-skills">He Is Questioning Our Skills</h2><p>When source code is open to the client, and he is technically capable of reading it, it is very possible that one day he will tell us that our code is crap and we have to learn how to program better. It has not happened in our projects for many years, but it has happened before, when we weren’t using static analysis as a mandatory step in our continuous integration pipeline.</p><p>Another funny possibility is when the client shows the source code to a “friend,” and he gives a “professional” opinion, which sounds like, “They don’t know what they are doing.” Once such an opinion hits your client’s ears, the project is at a significant risk of closure. It’ll be very difficult, almost impossible, to convince the client not to listen to the “friend” and continue to work with you. That’s why most outsourcers prefer to keep their sources private until the very end of the project, when the final invoice is paid.</p><aside class="quote">No matter how beautiful your architecture and your source code is, the “friend” will always be right.</aside><p>I think that an accidental appearance of a “friend” with a negative opinion is un-preventable. If it happens, it happens. You can’t avoid it. On the other hand, if you think your code is perfect and your team has only talented programmers writing beautiful software, this is not going to protect you either. An opinion coming from a “friend” won’t be objective; it will just be very personal, and that’s why it’s very credible. He is a friend of a client, and he doesn’t send him bills every week. Why would he lie? Of course, he is speaking from the heart! (I’m being sarcastic.) So, no matter how beautiful your architecture and your source code is, the “friend” will always be right.</p><p>In my opinion, the only way to prevent such a situation or minimize its consequences is to organize regular and systematic independent technical reviews. They will give confidence to the client that the team is not lying to him about the quality of the product and key technical decisions made internally.</p><hr /><p>To conclude, I strongly believe it is important to be honest and open with each client, no matter how difficult it is. Try to learn from every conflict with each client, and improve your management process and your principles of work. Hiding source code is not professional and makes you look bad in the eyes of your clients and the entire industry.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Most of our clients are rather surprised when we explain to them that they will have full access to the source code from the first day of the project. We let them see everything that is happening in the project, including the Git repository, bug reports, discussions between programmers, continuous integration fails, etc. They often tell me that other software development outsourcing teams keep this information in-house and deliver only final releases, rarely together with the source code.</p><p>I understand why other developers are trying to hide as much as possible. Giving a project sponsor full access to the development environment is not easy at all. Here is a summary of problems we’ve been having and our solutions. I hope they help you honestly show your clients all project internals and still keep them on board.</p>
    99 francs (2007) by Jan Kounen<figcaption id="822a28fd">99 francs (2007) by Jan Kounen</figcaption>
    <h2 id="he-is-breaking-our-process">He Is Breaking Our Process</h2><p>This is the most popular problem we face with our new clients. Once they gain access to the development environment, they try to give instructions directly to programmers, walking around our existing process. “I’m paying these guys; why can’t I tell them what to do?” is a very typical mindset. Instead of submitting requests through our standard change management mechanism, such a client goes directly to one of the programmers and tells him what should be fixed, how, and when. It’s micro-management in its worst form. We see it very often. What do we do?</p><aside class="quote">The simplest answer is that the client is a moron. Sometimes this is exactly the case, but it’s a rare one.</aside><p>First, we try to understand why it’s happening. The simplest answer is that the client is a moron. Sometimes this is exactly the case, but it’s a rare one. Much more often, our clients are not that bad. What is it, then? Why can’t they follow the process and abide by the rules? There are a few possible reasons.</p><p>Maybe the rules are not explained well. This is the most popular root cause—the rules of work are not clear enough for the client. He just doesn’t know what he is supposed to do in order to submit a request and get it implemented. To prevent this, we try to educate our clients at the beginning of a new project. We even write guidance manuals for clients. Most of them are happy to read them and learn the way we work, because they understand that this is the best way to achieve success while working with us.</p><aside class="youtube"> <div class="box"> YouTube video #Rip_04Bv3Jk<div class="play"></div></div><div>How to be Honest and Keep a Client?; 11 June 2017.</div></aside><p>Maybe our management is chaotic, and the client is trying to “organize” us by giving explicit instructions regarding the most important tasks. We’ve seen it before, and we are always trying to learn from this. As soon as we see that the client is trying to micro-manage us, we ask ourselves: “Is our process transparent enough? Do we give enough information to the client about milestones, risks, plans, costs, etc.?” In most cases, it’s our own fault, and we’re trying to learn and improve. If so, it’s important to react fast, before the client becomes too aggressive in his orders and instructions. It will be very difficult to escort him back to the normal process once he gets “micro-management” in his blood.</p><p>Maybe the client is not busy enough and has a lot of free time, which he is happy to spend by giving orders and distracting your team. I’ve seen this many times. A solution? Keep him busy. Turn him into a member of the team and assign him some tasks related to documentation and research. In my experience, most clients would be happy to do this work and help the project.</p><h2 id="he-is-asking-too-much">He Is Asking Too Much</h2><p>A technically-savvy client can turn the life of an architect into a nightmare by constantly asking him to explain every single technical decision made, from “Why PostgreSQL instead of MySQL?” to “Why doesn’t this method throw a checked exception?” Constantly answering such questions can turn a project into a school of programming. Even though he is paying for our time, that doesn’t mean we should teach him how to develop software, right? On the other hand, he is interested in knowing how his software is developed and how it works. It’s a fair request, isn’t it?</p><aside class="quote">He is interested in knowing how his software is developed and how it works. It’s a fair request, isn’t it?</aside><p>I believe there is a win-win solution to this problem. Here is how we manage it. First of all, we make all his requests formal. We ask a client to create a new ticket for each request, properly explaining what is not clear and how much detail is expected in the explanation.</p><p>Second, we look at such requests positively—they are good indicators of certain inconsistencies in the software. If it’s not clear for the client why PostgreSQL is used and not MySQL, it’s a fault of our architect. He didn’t document his decision and didn’t explain how it was made, what other options were considered, what selection criteria were applied, etc. Thus, a request from a client is a bug we get for free. So, we look at it positively.</p><p>Finally, we charge our clients for the answers given. Every question, submitted as a ticket, goes through the full flow and gets billed just as any other ticket. This approach prevents the client from asking for too much. He realizes that we’re ready to explain anything he wants, but he will pay for it.</p><h2 id="he-is-telling-too-much">He Is Telling Too Much</h2><p>This problem is even bigger than the previous one. Some clients believe they are savvy enough to argue with our architect and our programmers about how the software should be developed. They don’t just ask why PostgreSQL is used, they tell us that we should use MySQL, because “I know that it’s a great database; my friend is using it, and his business is growing!” Sometimes it gets even worse, when suggestions are directed at every class or even a method, like “You should use a Singleton pattern here!”</p><p>Our first choice is to agree and do what he wants. But it’s a road to nowhere. Once you do it, your project is ruined, and you should start thinking about a divorce with this client. Your entire team will quickly turn into a group of coding monkeys, micro-managed by someone with some cash. It’s a very wrong direction; don’t even think about going there.</p><p>The second choice is to tell the client to mind his own business and let us do ours. He hired us because we’re professional enough to develop the software according to his requirements. If he questions our capabilities, he is free to change the contractor. But until then, he has to trust our decisions. Will this work? I doubt it. It’s the same as giving him the finger. He will get offended, and you won’t get anything.</p><p>The solution here is to turn the client’s demands into project requirements. Most of them will be lost in the process, because they won’t be sane enough to form a good requirement. Others will be documented, estimated, and crossed-out by the client himself, because he will realize they are pointless or too expensive. Only a few of them will survive, since they will be reasonable enough. And they will help the project. So it is also a win-win solution.</p><aside class="quote">Never take a client’s demands directly to execution, but rather use them first to amend the requirements documentation.</aside><p>For example, he says that “you should use MySQL because it’s great.” You tell him that the project requirements document doesn’t limit you to choose whichever database you like. Should it? He says yes, of course! OK, let’s try to document such a requirement. How will it sound? How about, “We should only use great databases?” Sound correct? If so, then PostgreSQL satisfies this requirement. Problem solved; let us continue to do our work. He will have a hard time figuring out how to write a requirement in a way that disallows PostgreSQL but allows MySQL. It is simply not possible in most cases.</p><p>Sometimes, though, it will make sense; for example, “We should use a database server that understands our legacy data in MySQL format.” This is a perfectly sane requirement, and the only way to satisfy it is to use MySQL.</p><p>Thus, my recommendation is to never take a client’s demands directly to execution, but rather use them first to amend the requirements documentation. Even if you don’t have such documentation, create a simple one-page document. Agree with the client that you work against this document, and when anyone wants to change something, you first have to amend the document and then have your team ensure the software satisfies it. This kind of discipline will be accepted by any client and will protect you against sudden and distracting corrections.</p><h2 id="he-is-questioning-our-skills">He Is Questioning Our Skills</h2><p>When source code is open to the client, and he is technically capable of reading it, it is very possible that one day he will tell us that our code is crap and we have to learn how to program better. It has not happened in our projects for many years, but it has happened before, when we weren’t using static analysis as a mandatory step in our continuous integration pipeline.</p><p>Another funny possibility is when the client shows the source code to a “friend,” and he gives a “professional” opinion, which sounds like, “They don’t know what they are doing.” Once such an opinion hits your client’s ears, the project is at a significant risk of closure. It’ll be very difficult, almost impossible, to convince the client not to listen to the “friend” and continue to work with you. That’s why most outsourcers prefer to keep their sources private until the very end of the project, when the final invoice is paid.</p><aside class="quote">No matter how beautiful your architecture and your source code is, the “friend” will always be right.</aside><p>I think that an accidental appearance of a “friend” with a negative opinion is un-preventable. If it happens, it happens. You can’t avoid it. On the other hand, if you think your code is perfect and your team has only talented programmers writing beautiful software, this is not going to protect you either. An opinion coming from a “friend” won’t be objective; it will just be very personal, and that’s why it’s very credible. He is a friend of a client, and he doesn’t send him bills every week. Why would he lie? Of course, he is speaking from the heart! (I’m being sarcastic.) So, no matter how beautiful your architecture and your source code is, the “friend” will always be right.</p><p>In my opinion, the only way to prevent such a situation or minimize its consequences is to organize regular and systematic independent technical reviews. They will give confidence to the client that the team is not lying to him about the quality of the product and key technical decisions made internally.</p><hr /><p>To conclude, I strongly believe it is important to be honest and open with each client, no matter how difficult it is. Try to learn from every conflict with each client, and improve your management process and your principles of work. Hiding source code is not professional and makes you look bad in the eyes of your clients and the entire industry.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> You Do Need Independent Technical Reviews! </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/12/18/independent-technical-reviews.html>12 Best</li> <li /2014/12/18/independent-technical-reviews.html>All 292</li> <li /2014/12/18/independent-technical-reviews.html>Webinars</li> <li /2014/12/18/independent-technical-reviews.html>Talks</li> <li /2014/12/18/independent-technical-reviews.html>Books</li> <li /2014/12/18/independent-technical-reviews.html>Papers</li> <li /2014/12/18/independent-technical-reviews.html>Pets</li> <li /2014/12/18/independent-technical-reviews.html class=”highlighted”>Trainings</li> <li /2014/12/18/independent-technical-reviews.html>Award</li> <li /2014/12/18/independent-technical-reviews.html>Testimonials</li> <li /2014/12/18/independent-technical-reviews.html>Shift-M</li> <li /2014/12/18/independent-technical-reviews.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">You Do Need Independent Technical Reviews!</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Do you have a team of brilliant and enthusiastic programmers? Of course! You’ve carefully chosen them from a hundred candidates! Are they passionate about the product? Absolutely! They use cutting-edge technologies, never sleep, and hardly eat or drink anything except coffee! Do they believe in your business success? No doubts about it; they live and breathe all those features, releases, continuous delivery, user experience, etc. Are you sure they are developing the product correctly? Well, yes, you’re pretty sure; why wouldn’t they? …</p>
    Arizona Dream (1992) by Emir Kusturica<figcaption id="4382e3b5">Arizona Dream (1992) by Emir Kusturica</figcaption>
    <p>Does this sound familiar? I can’t count how many times I’ve heard these stories told by startup founders. Most of them are in love with their teams … until that day when it’s time to hire a new one. There could be many possible reasons for such a fiasco, but one of them is a lack of regular, systematic, and independent technical reviews. Nothing demotivates a development team more than a lack of attention to their deliverables. On the other hand, a regular reconciliation of their results and your quality expectations is one of the key factors that will guarantee technical success for your startup. Below I summarize my experience with organizing such technical reviews.</p><p>An independent review is when you ask someone outside of your team to look at your source code and other technical resources and give you an objective opinion about them. Every modern software team should also use internal code reviews, which is is something else entirely. An internal review occurs when one programmer shows his code to other peers on the team and asks their opinion. This usually happens as a daily activity and has nothing to do with independent reviews.</p><p>An independent review is performed by a programmer who knows nothing about your team. He comes on board, checks out the code from your repository, spends a few hours (or days) looking at it and trying to understand what it does. Then, he tells you what is wrong and where. He explains how he would do it better, where he would change it, and what he would do instead. Then, you pay him and he leaves. You may never see him again, but his conclusions and suggestions help you check the reality of your code and evaluate how your team is really doing.</p>
    badge
    <p>We, at Zerocracy, do independent reviews with every project of ours, and this is a list of principles we use:</p><p>Make Independent Reviews Systematic. This is the first and most important rule—organize such technical reviews regularly. Moreover, inform your team about the schedule, and let them be prepared for the reviews. Once a month is a good practice, according to my experience. Depending on your source code size, a full review should take from two to eight hours. Don’t spend more than eight hours; there is no point in going too deep into the code during independent reviews.</p><p>Pay for Bugs Found. We always pay for bugs, not for the time spent finding them. We ask our reviewers to look at the code and report as many bugs as we think we need. For each bug, we pay 15 minutes for their time. In other words, we assume that a good reviewer can find and report approximately four problems in one hour. For example, a reviewer charges $150 per hour. We hire him and ask him to find and report the 20 most critical issues he can discover. Our estimate is that he should spend five hours on this work. Thus, he will get $750 when we have 20 bugs in our tracking system reported by him. If he finds fewer, he gets proportionally less money. This payment schedule will help you focus your reviewer on the main objective of the review process—finding and reporting issues. There are no other goals. The only thing you’re interested in is knowing what the issues with your current technical solution are. That’s what you’re paying for.</p><p>Hire the Best and Pay Well. My experience tells me that the position of an independent reviewer is a very important one. He is not just a programmer but more of an architect who is capable of looking at the solution from a very high level of abstraction, while at the same time paying a lot of attention to details; he should be very good at designing similar systems; he should know how to report a bug correctly and with enough detail; he should understand your business domain; etc. Besides all that, he should be well motivated to help you. You’re not hiring him for full-time work but rather just for a few-hour gig. My advice is to try to get the best guys, and pay them as much as they ask, usually over $100 per hour. Don’t negotiate, just pay. It’s just a few hundred dollars for you, but the effect of their contribution will be huge.</p><p>Ask For and Expect Criticism. It is a very common mistake to ask a reviewer, “Do you like our code?” Don’t expect him to tell you how great your code is. This is not what you’re paying him for! You already have a full team of programmers for cheering you up; they can tell you a lot about the code they are creating and how awesome it is. You don’t want to hear this again from the reviewer. Instead, you want to know what is wrong and needs to be fixed. So your questions should sound like, “What problems do you think we should fix first?” Some reviewers will try to please you with positive comments, but ignore that flattery and bring them back to the main goal—bugs. The payment schedule explained above should help.</p><p>Regularly Change Reviewers. Try not to use the same reviewer more than once on the same project (I mean the same code base). I believe the reason here is obvious, but let me re-iterate: You don’t need your reviewer to be nice to you and tell you how great your code is. You want him to be objective and focused on problems, not on bright sides. If you hire the same person again and again, psychologically you make him engaged to the source code. He’s seen it once; now he has to see it again. He already told you about some problem, and now he has to repeat it again. He won’t feel comfortable doing it. Instead, he will start feeling like a member of the team and will feel responsible for the source code and its mistakes. He, as any other team member, will start hiding issues instead of revealing them. Thus, for every independent technical review, get a new person.</p><p>Be Polite and Honest With Your Team. Independent reviews can be rather offensive to your programmers. They may think that you don’t trust them. They may feel that you don’t respect them as technical specialists. They may even decide that you’re getting ready to fire them all and are currently looking for new people. This is a very possible and very destructive side effect of an independent review. How do you avoid it? I can’t give you universal advice, but the best suggestion I can give is this: be honest with them. Tell them that the quality of the product is critical for you and your business. Explain to them that the business is paying them for their work and that in order to keep paychecks coming, you have to stress quality control—regularly, objectively, independently, and honestly. In the end, if you manage to organize reviews as this article explains, the team will be very thankful to you. They will gain a lot of new ideas and thoughts from every review and will ask you to repeat them regularly.</p><p>Review From Day One. Don’t wait until the end of the project! I’ve seen this mistake many times. Very often startup founders think that until the product is done and ready for the market, they shouldn’t distract their team. They think they should let the team work toward project milestones and take care of quality later, “when we have a million visitors per day.” This day will never come if you let your team run without control! Start conducting independent reviews from the moment your Git repository has its first file. Until the repository is big enough, you may only spend $300 once a month to receive an objective, independent opinion about its quality. Will this ruin your budget?</p><p>Prohibit Discussions, and Ask for Formal Reporting. Don’t let your reviewers talk to the team. If you do, the entire idea of a review being independent falls apart. If a reviewer is able to ask informal questions and discuss your system design with your programmers, their answers will satisfy him, and he will move on. But you, the owner of the business, will stay exactly where you were before the review. The point of the review is not to make the reviewer happy. It is exactly the opposite. You want to make him confused! If he is confused, your design is wrong and he feels the need to report a bug. The source code should speak for itself, and it should be easy enough for a stranger (the reviewer) to understand how it works. If this is not the case, there is something wrong that should be fixed.</p><p>Treat Any Question as a Bug. Don’t expect a review to produce any bugs in functionality, like “I click this button and the system crashes.” This will happen rarely, if ever. Your team is very good at discovering these issues and fixing them. Independent reviews are not about that kind of bugs. The main goal of an independent review is to discover bugs in the architecture and design. Your product may work, but its architecture may have serious design flaws that won’t allow you, for example, to handle exponential growth in web traffic. An independent reviewer will help you find those flaws and address them sooner than later. In order to get bugs of that kind from the reviewer, you should encourage him to report anything he doesn’t like—unmotivated use of a technology, lack of documentation, unclear purpose of a file, absence of a unit test, etc. Remember, the reviewer is not a member of your team and has his own ideas about the technologies you’re using and software development in general. You’re interested in matching his vision with your team’s. Then, you’re interested in fixing all critical mismatches.</p><p>Review Everything, Not Just Source Code. Let your reviewer look at all technical resources you have, not just source code files (.java, .rb, .php, etc.) Give him access to the database schema, continuous integration panel, build environment, issue tracking system, plans and schedules, work agendas, up-time reports, deployment pipeline, production logs, customer bug reports, statistics, etc. Everything that could help him understand how your system works, and more importantly, where and how it breaks, is very useful. Don’t limit the reviewer to the source code only—this is simply not enough! Let him see the big picture, and you will get a much more detailed and professional report.</p><p>Track How Inconsistencies Are Resolved. Once you get a report from the reviewer, make sure that the most important issues immediately get into your team’s backlog. Then, make sure they are addressed and closed. That doesn’t mean you should fix them all and listen to everything said by the reviewer. Definitely not! Your architect runs the show, not the reviewer. Your architect should decide what is right and what is wrong in the technical implementation of the product. But it’s important to make him resolve all concerns raised by the reviewer. Very often you will get answers like these from him: “We don’t care about it now,” “we won’t fix it until the next release,” or “he is wrong; we’re doing it better.” These answers are perfectly valid, but they have to be given (reviewers are people and they also make mistakes). The answers will help you, the founder, understand what your team is doing and how well they understand their business.</p><hr /><p>If you can offer more suggestions, based on your experience, please post them below in the comments, and I’ll add them to the list. I’m still thinking that I may have forgotten something important :)</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Do you have a team of brilliant and enthusiastic programmers? Of course! You’ve carefully chosen them from a hundred candidates! Are they passionate about the product? Absolutely! They use cutting-edge technologies, never sleep, and hardly eat or drink anything except coffee! Do they believe in your business success? No doubts about it; they live and breathe all those features, releases, continuous delivery, user experience, etc. Are you sure they are developing the product correctly? Well, yes, you’re pretty sure; why wouldn’t they? …</p>
    Arizona Dream (1992) by Emir Kusturica<figcaption id="4382e3b5">Arizona Dream (1992) by Emir Kusturica</figcaption>
    <p>Does this sound familiar? I can’t count how many times I’ve heard these stories told by startup founders. Most of them are in love with their teams … until that day when it’s time to hire a new one. There could be many possible reasons for such a fiasco, but one of them is a lack of regular, systematic, and independent technical reviews. Nothing demotivates a development team more than a lack of attention to their deliverables. On the other hand, a regular reconciliation of their results and your quality expectations is one of the key factors that will guarantee technical success for your startup. Below I summarize my experience with organizing such technical reviews.</p><p>An independent review is when you ask someone outside of your team to look at your source code and other technical resources and give you an objective opinion about them. Every modern software team should also use internal code reviews, which is is something else entirely. An internal review occurs when one programmer shows his code to other peers on the team and asks their opinion. This usually happens as a daily activity and has nothing to do with independent reviews.</p><p>An independent review is performed by a programmer who knows nothing about your team. He comes on board, checks out the code from your repository, spends a few hours (or days) looking at it and trying to understand what it does. Then, he tells you what is wrong and where. He explains how he would do it better, where he would change it, and what he would do instead. Then, you pay him and he leaves. You may never see him again, but his conclusions and suggestions help you check the reality of your code and evaluate how your team is really doing.</p>
    badge
    <p>We, at Zerocracy, do independent reviews with every project of ours, and this is a list of principles we use:</p><p>Make Independent Reviews Systematic. This is the first and most important rule—organize such technical reviews regularly. Moreover, inform your team about the schedule, and let them be prepared for the reviews. Once a month is a good practice, according to my experience. Depending on your source code size, a full review should take from two to eight hours. Don’t spend more than eight hours; there is no point in going too deep into the code during independent reviews.</p><p>Pay for Bugs Found. We always pay for bugs, not for the time spent finding them. We ask our reviewers to look at the code and report as many bugs as we think we need. For each bug, we pay 15 minutes for their time. In other words, we assume that a good reviewer can find and report approximately four problems in one hour. For example, a reviewer charges $150 per hour. We hire him and ask him to find and report the 20 most critical issues he can discover. Our estimate is that he should spend five hours on this work. Thus, he will get $750 when we have 20 bugs in our tracking system reported by him. If he finds fewer, he gets proportionally less money. This payment schedule will help you focus your reviewer on the main objective of the review process—finding and reporting issues. There are no other goals. The only thing you’re interested in is knowing what the issues with your current technical solution are. That’s what you’re paying for.</p><p>Hire the Best and Pay Well. My experience tells me that the position of an independent reviewer is a very important one. He is not just a programmer but more of an architect who is capable of looking at the solution from a very high level of abstraction, while at the same time paying a lot of attention to details; he should be very good at designing similar systems; he should know how to report a bug correctly and with enough detail; he should understand your business domain; etc. Besides all that, he should be well motivated to help you. You’re not hiring him for full-time work but rather just for a few-hour gig. My advice is to try to get the best guys, and pay them as much as they ask, usually over $100 per hour. Don’t negotiate, just pay. It’s just a few hundred dollars for you, but the effect of their contribution will be huge.</p><p>Ask For and Expect Criticism. It is a very common mistake to ask a reviewer, “Do you like our code?” Don’t expect him to tell you how great your code is. This is not what you’re paying him for! You already have a full team of programmers for cheering you up; they can tell you a lot about the code they are creating and how awesome it is. You don’t want to hear this again from the reviewer. Instead, you want to know what is wrong and needs to be fixed. So your questions should sound like, “What problems do you think we should fix first?” Some reviewers will try to please you with positive comments, but ignore that flattery and bring them back to the main goal—bugs. The payment schedule explained above should help.</p><p>Regularly Change Reviewers. Try not to use the same reviewer more than once on the same project (I mean the same code base). I believe the reason here is obvious, but let me re-iterate: You don’t need your reviewer to be nice to you and tell you how great your code is. You want him to be objective and focused on problems, not on bright sides. If you hire the same person again and again, psychologically you make him engaged to the source code. He’s seen it once; now he has to see it again. He already told you about some problem, and now he has to repeat it again. He won’t feel comfortable doing it. Instead, he will start feeling like a member of the team and will feel responsible for the source code and its mistakes. He, as any other team member, will start hiding issues instead of revealing them. Thus, for every independent technical review, get a new person.</p><p>Be Polite and Honest With Your Team. Independent reviews can be rather offensive to your programmers. They may think that you don’t trust them. They may feel that you don’t respect them as technical specialists. They may even decide that you’re getting ready to fire them all and are currently looking for new people. This is a very possible and very destructive side effect of an independent review. How do you avoid it? I can’t give you universal advice, but the best suggestion I can give is this: be honest with them. Tell them that the quality of the product is critical for you and your business. Explain to them that the business is paying them for their work and that in order to keep paychecks coming, you have to stress quality control—regularly, objectively, independently, and honestly. In the end, if you manage to organize reviews as this article explains, the team will be very thankful to you. They will gain a lot of new ideas and thoughts from every review and will ask you to repeat them regularly.</p><p>Review From Day One. Don’t wait until the end of the project! I’ve seen this mistake many times. Very often startup founders think that until the product is done and ready for the market, they shouldn’t distract their team. They think they should let the team work toward project milestones and take care of quality later, “when we have a million visitors per day.” This day will never come if you let your team run without control! Start conducting independent reviews from the moment your Git repository has its first file. Until the repository is big enough, you may only spend $300 once a month to receive an objective, independent opinion about its quality. Will this ruin your budget?</p><p>Prohibit Discussions, and Ask for Formal Reporting. Don’t let your reviewers talk to the team. If you do, the entire idea of a review being independent falls apart. If a reviewer is able to ask informal questions and discuss your system design with your programmers, their answers will satisfy him, and he will move on. But you, the owner of the business, will stay exactly where you were before the review. The point of the review is not to make the reviewer happy. It is exactly the opposite. You want to make him confused! If he is confused, your design is wrong and he feels the need to report a bug. The source code should speak for itself, and it should be easy enough for a stranger (the reviewer) to understand how it works. If this is not the case, there is something wrong that should be fixed.</p><p>Treat Any Question as a Bug. Don’t expect a review to produce any bugs in functionality, like “I click this button and the system crashes.” This will happen rarely, if ever. Your team is very good at discovering these issues and fixing them. Independent reviews are not about that kind of bugs. The main goal of an independent review is to discover bugs in the architecture and design. Your product may work, but its architecture may have serious design flaws that won’t allow you, for example, to handle exponential growth in web traffic. An independent reviewer will help you find those flaws and address them sooner than later. In order to get bugs of that kind from the reviewer, you should encourage him to report anything he doesn’t like—unmotivated use of a technology, lack of documentation, unclear purpose of a file, absence of a unit test, etc. Remember, the reviewer is not a member of your team and has his own ideas about the technologies you’re using and software development in general. You’re interested in matching his vision with your team’s. Then, you’re interested in fixing all critical mismatches.</p><p>Review Everything, Not Just Source Code. Let your reviewer look at all technical resources you have, not just source code files (.java, .rb, .php, etc.) Give him access to the database schema, continuous integration panel, build environment, issue tracking system, plans and schedules, work agendas, up-time reports, deployment pipeline, production logs, customer bug reports, statistics, etc. Everything that could help him understand how your system works, and more importantly, where and how it breaks, is very useful. Don’t limit the reviewer to the source code only—this is simply not enough! Let him see the big picture, and you will get a much more detailed and professional report.</p><p>Track How Inconsistencies Are Resolved. Once you get a report from the reviewer, make sure that the most important issues immediately get into your team’s backlog. Then, make sure they are addressed and closed. That doesn’t mean you should fix them all and listen to everything said by the reviewer. Definitely not! Your architect runs the show, not the reviewer. Your architect should decide what is right and what is wrong in the technical implementation of the product. But it’s important to make him resolve all concerns raised by the reviewer. Very often you will get answers like these from him: “We don’t care about it now,” “we won’t fix it until the next release,” or “he is wrong; we’re doing it better.” These answers are perfectly valid, but they have to be given (reviewers are people and they also make mistakes). The answers will help you, the founder, understand what your team is doing and how well they understand their business.</p><hr /><p>If you can offer more suggestions, based on your experience, please post them below in the comments, and I’ll add them to the list. I’m still thinking that I may have forgotten something important :)</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> How Immutability Helps </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/11/07/how-immutability-helps.html>12 Best</li> <li /2014/11/07/how-immutability-helps.html>All 292</li> <li /2014/11/07/how-immutability-helps.html>Webinars</li> <li /2014/11/07/how-immutability-helps.html>Talks</li> <li /2014/11/07/how-immutability-helps.html>Books</li> <li /2014/11/07/how-immutability-helps.html>Papers</li> <li /2014/11/07/how-immutability-helps.html>Pets</li> <li /2014/11/07/how-immutability-helps.html class=”highlighted”>Trainings</li> <li /2014/11/07/how-immutability-helps.html>Award</li> <li /2014/11/07/how-immutability-helps.html>Testimonials</li> <li /2014/11/07/how-immutability-helps.html>Shift-M</li> <li /2014/11/07/how-immutability-helps.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">How Immutability Helps</h1><aside class='book'>book coverRead more about this subject in Section 2.6
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>In a few recent posts, including Getters/Setters. Evil. Period. Objects Should Be Immutable, and Dependency Injection Containers are Code Polluters, I universally labeled all mutable objects with “setters” (object methods starting with set) evil. My argumentation was based mostly on metaphors and abstract examples. Apparently, this wasn’t convincing enough for many of you—I received a few requests asking to provide more specific and practical examples.</p><p>Thus, in order to illustrate my strongly negative attitude to “mutability via setters,” I took an existing commons-email Java library from Apache and re-designed it my way, without setters and with “object thinking” in mind. I released my library as part of the jcabi family—jcabi-email. Let’s see what benefits we get from a “pure” object-oriented and immutable approach, without getters.</p><p>Here is how your code will look, if you send an email using commons-email:</p>
    <pre>Email email = new SimpleEmail(); email.setHostName("smtp.googlemail.com"); email.setSmtpPort(465); email.setAuthenticator(new DefaultAuthenticator("user", "pwd")); email.setFrom("yegor256@gmail.com", "Yegor Bugayenko"); email.addTo("dude@jcabi.com"); email.setSubject("how are you?"); email.setMsg("Dude, how are you?"); email.send();</pre>
    <p>Here is how you do the same with jcabi-email:</p>
    <pre>Postman postman = new Postman.Default( new SMTP("smtp.googlemail.com", 465, "user", "pwd") ); Envelope envelope = new Envelope.MIME( new Array<Stamp>( new StSender("Yegor Bugayenko <yegor256@gmail.com>"), new StRecipient("dude@jcabi.com"), new StSubject("how are you?") ), new Array<Enclosure>( new EnPlain("Dude, how are you?") ) ); postman.send(envelope);</pre>
    <p>I think the difference is obvious.</p><p>In the first example, you’re dealing with a monster class that can do everything for you, including sending your MIME message via SMTP, creating the message, configuring its parameters, adding MIME parts to it, etc. The Email class from commons-email is really a huge class—33 private properties, over a hundred methods, about two thousands lines of code. First, you configure the class through a bunch of setters and then you ask it to send() an email for you.</p><aside class="youtube"> <div class="box"> YouTube video #KwP7Ay9Z-hc<div class="play"></div></div><div>Immutable Objects vs. Common Sense (webinar #2); 6 May 2015.</div></aside><p>In the second example, we have seven objects instantiated via seven new calls. Postman is responsible for packaging a MIME message; SMTP is responsible for sending it via SMTP; stamps (StSender, StRecipient, and StSubject) are responsible for configuring the MIME message before delivery; enclosure EnPlain is responsible for creating a MIME part for the message we’re going to send. We construct these seven objects, encapsulating one into another, and then we ask the postman to send() the envelope for us.</p><h2 id="whats-wrong-with-a-mutable-email">What’s Wrong With a Mutable Email?</h2><p>From a user perspective, there is almost nothing wrong. Email is a powerful class with multiple controls—just hit the right one and the job gets done. However, from a developer perspective Email class is a nightmare. Mostly because the class is very big and difficult to maintain.</p><p>Because the class is so big, every time you want to extend it by introducing a new method, you’re facing the fact that you’re making the class even worse—longer, less cohesive, less readable, less maintainable, etc. You have a feeling that you’re digging into something dirty and that there is no hope to make it cleaner, ever. I’m sure, you’re familiar with this feeling—most legacy applications look that way. They have huge multi-line “classes” (in reality, COBOL programs written in Java) that were inherited from a few generations of programmers before you. When you start, you’re full of energy, but after a few minutes of scrolling such a “class” you say—“screw it, it’s almost Saturday.”</p><aside class="youtube"> <div class="box"> YouTube video #EnhRgXrHCC4<div class="play"></div></div><div>How Immutability Helps in OOP (in Russian with English subtitles); 21 May 2016.</div></aside><p>Because the class is so big, there is no data hiding or encapsulation any more—33 variables are accessible by over 100 methods. What is hidden? This Email.java file in reality is a big, procedural 2000-line script, called a “class” by mistake. Nothing is hidden, once you cross the border of the class by calling one of its methods. After that, you have full access to all the data you may need. Why is this bad? Well, why do we need encapsulation in the first place? In order to protect one programmer from another, aka defensive programming. While I’m busy changing the subject of the MIME message, I want to be sure that I’m not interfered with by some other method’s activity, that is changing a sender and touching my subject by mistake. Encapsulation helps us narrow down the scope of the problem, while this Email class is doing exactly the opposite.</p><p>Because the class is so big, its unit testing is even more complicated than the class itself. Why? Because of multiple inter-dependencies between its methods and properties. In order to test setCharset() you have to prepare the entire object by calling a few other methods, then you have to call send() to make sure the message being sent actually uses the encoding you specified. Thus, in order to test a one-line method setCharset() you run the entire integration testing scenario of sending a full MIME message through SMTP. Obviously, if something gets changed in one of the methods, almost every test method will be affected. In other words, tests are very fragile, unreliable and over-complicated.</p><p>I can go on and on with this “because the class is so big,” but I think it is obvious that a small, cohesive class is always better than a big one. It is obvious to me, to you, and to any object-oriented programmer. But why is it not so obvious to the developers of Apache Commons Email? I don’t think they are stupid or un-educated. What is it then?</p><h2 id="how-and-why-did-it-happen">How and Why Did It Happen?</h2><p>This is how it always happens. You start to design a class as something cohesive, solid, and small. Your intentions are very positive. Very soon you realize that there is something else that this class has to do. Then, something else. Then, even more.</p><p>The best way to make your class more and more powerful is by adding setters that inject configuration parameters into the class so that it can process them inside, isn’t it?</p><aside class="youtube"> <div class="box"> YouTube video #p7m7_iiqaHI<div class="play"></div></div><div>How Much Immutability Is Enough?; 19 May 2016.</div></aside><p>This is the root cause of the problem! The root cause is our ability to insert data into mutable objects via configuration methods, also known as “setters.” When an object is mutable and allows us to add setters whenever we want, we will do it without limits.</p><p>Let me put it this way—mutable classes tend to grow in size and lose cohesiveness.</p><p>If commons-email authors made this Email class immutable in the beginning, they wouldn’t have been able to add so many methods into it and encapsulate so many properties. They wouldn’t be able to turn it into a monster. Why? Because an immutable object only accepts a state through a constructor. Can you imagine a 33-argument constructor? Of course, not.</p><p>When you make your class immutable in the first place, you are forced to keep it cohesive, small, solid and robust. Because you can’t encapsulate too much and you can’t modify what’s encapsulated. Just two or three arguments of a constructor and you’re done.</p><h2 id="how-did-i-design-an-immutable-email">How Did I Design An Immutable Email?</h2>
    badge
    <p>When I was designing jcabi-email I started with a small and simple class: Postman. Well, it is an interface, since I never make interface-less classes. So, Postman is… a post man. He is delivering messages to other people. First, I created a default version of it (I omit the ctor, for the sake of brevity):</p>
    <pre>import javax.mail.Message; @Immutable class Postman.Default implements Postman { private final String host; private final int port; private final String user; private final String password; @Override void send(Message msg) { // create SMTP session // create transport // transport.connect(this.host, this.port, etc.) // transport.send(msg) // transport.close(); } }</pre>
    <p>Good start, it works. What now? Well, the Message is difficult to construct. It is a complex class from JDK that requires some manipulations before it can become a nice HTML email. So I created an envelope, which will build this complex object for me (pay attention, both Postman and Envelope are immutable and annotated with @Immutable from jcabi-aspects):</p>
    <pre>@Immutable interface Envelope { Message unwrap(); }</pre>
    <p>I also refactor the Postman to accept an envelope, not a message:</p>
    <pre>@Immutable interface Postman { void send(Envelope env); }</pre>
    <p>So far, so good. Now let’s try to create a simple implementation of Envelope:</p>
    <pre>@Immutable class MIME implements Envelope { @Override public Message unwrap() { return new MimeMessage( Session.getDefaultInstance(new Properties()) ); } }</pre>
    <p>It works, but it does nothing useful yet. It only creates an absolutely empty MIME message and returns it. How about adding a subject to it and both To: and From: addresses (pay attention, MIME class is also immutable):</p>
    <pre>@Immutable class Envelope.MIME implements Envelope { private final String subject; private final String from; private final Array<String> to; public MIME(String subj, String sender, Iterable<String> rcpts) { this.subject = subj; this.from = sender; this.to = new Array<String>(rcpts); } @Override public Message unwrap() { Message msg = new MimeMessage( Session.getDefaultInstance(new Properties()) ); msg.setSubject(this.subject); msg.setFrom(new InternetAddress(this.from)); for (String email : this.to) { msg.setRecipient( Message.RecipientType.TO, new InternetAddress(email) ); } return msg; } }</pre>
    <p>Looks correct and it works. But it is still too primitive. How about CC: and BCC:? What about email text? How about PDF enclosures? What if I want to specify the encoding of the message? What about Reply-To?</p><p>Can I add all these parameters to the constructor? Remember, the class is immutable and I can’t introduce the setReplyTo() method. I have to pass the replyTo argument into its constructor. It’s impossible, because the constructor will have too many arguments, and nobody will be able to use it.</p><p>So, what do I do?</p><p>Well, I started to think: how can we break the concept of an “envelope” into smaller concepts—and this what I invented. Like a real-life envelope, my MIME object will have stamps. Stamps will be responsible for configuring an object Message (again, Stamp is immutable, as well as all its implementers):</p>
    <pre>@Immutable interface Stamp { void attach(Message message); }</pre>
    <p>Now, I can simplify my MIME class to the following:</p>
    <pre>@Immutable class Envelope.MIME implements Envelope { private final Array<Stamp> stamps; public MIME(Iterable<Stamp> stmps) { this.stamps = new Array<Stamp>(stmps); } @Override public Message unwrap() { Message msg = new MimeMessage( Session.getDefaultInstance(new Properties()) ); for (Stamp stamp : this.stamps) { stamp.attach(msg); } return msg; } }</pre>
    <p>Now, I will create stamps for the subject, for To:, for From:, for CC:, for BCC:, etc. As many stamps as I like. The class MIME will stay the same—small, cohesive, readable, solid, etc.</p><p>What is important here is why I made the decision to refactor while the class was relatively small. Indeed, I started to worry about these stamp classes when my MIME class was just 25 lines in size.</p><p>That is exactly the point of this article—immutability forces you to design small and cohesive objects.</p><p>Without immutability, I would have gone the same direction as commons-email. My MIME class would grow in size and sooner or later would become as big as Email from commons-email. The only thing that stopped me was the necessity to refactor it, because I wasn’t able to pass all arguments through a constructor.</p><p>Without immutability, I wouldn’t have had that motivator and I would have done what Apache developers did with commons-email—bloat the class and turn it into an unmaintainable monster.</p><p>That’s jcabi-email. I hope this example was illustrative enough and that you will start writing cleaner code with immutable objects.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>In a few recent posts, including Getters/Setters. Evil. Period. Objects Should Be Immutable, and Dependency Injection Containers are Code Polluters, I universally labeled all mutable objects with “setters” (object methods starting with set) evil. My argumentation was based mostly on metaphors and abstract examples. Apparently, this wasn’t convincing enough for many of you—I received a few requests asking to provide more specific and practical examples.</p><p>Thus, in order to illustrate my strongly negative attitude to “mutability via setters,” I took an existing commons-email Java library from Apache and re-designed it my way, without setters and with “object thinking” in mind. I released my library as part of the jcabi family—jcabi-email. Let’s see what benefits we get from a “pure” object-oriented and immutable approach, without getters.</p><p>Here is how your code will look, if you send an email using commons-email:</p>
    <pre>Email email = new SimpleEmail(); email.setHostName("smtp.googlemail.com"); email.setSmtpPort(465); email.setAuthenticator(new DefaultAuthenticator("user", "pwd")); email.setFrom("yegor256@gmail.com", "Yegor Bugayenko"); email.addTo("dude@jcabi.com"); email.setSubject("how are you?"); email.setMsg("Dude, how are you?"); email.send();</pre>
    <p>Here is how you do the same with jcabi-email:</p>
    <pre>Postman postman = new Postman.Default( new SMTP("smtp.googlemail.com", 465, "user", "pwd") ); Envelope envelope = new Envelope.MIME( new Array<Stamp>( new StSender("Yegor Bugayenko <yegor256@gmail.com>"), new StRecipient("dude@jcabi.com"), new StSubject("how are you?") ), new Array<Enclosure>( new EnPlain("Dude, how are you?") ) ); postman.send(envelope);</pre>
    <p>I think the difference is obvious.</p><p>In the first example, you’re dealing with a monster class that can do everything for you, including sending your MIME message via SMTP, creating the message, configuring its parameters, adding MIME parts to it, etc. The Email class from commons-email is really a huge class—33 private properties, over a hundred methods, about two thousands lines of code. First, you configure the class through a bunch of setters and then you ask it to send() an email for you.</p><aside class="youtube"> <div class="box"> YouTube video #KwP7Ay9Z-hc<div class="play"></div></div><div>Immutable Objects vs. Common Sense (webinar #2); 6 May 2015.</div></aside><p>In the second example, we have seven objects instantiated via seven new calls. Postman is responsible for packaging a MIME message; SMTP is responsible for sending it via SMTP; stamps (StSender, StRecipient, and StSubject) are responsible for configuring the MIME message before delivery; enclosure EnPlain is responsible for creating a MIME part for the message we’re going to send. We construct these seven objects, encapsulating one into another, and then we ask the postman to send() the envelope for us.</p><h2 id="whats-wrong-with-a-mutable-email">What’s Wrong With a Mutable Email?</h2><p>From a user perspective, there is almost nothing wrong. Email is a powerful class with multiple controls—just hit the right one and the job gets done. However, from a developer perspective Email class is a nightmare. Mostly because the class is very big and difficult to maintain.</p><p>Because the class is so big, every time you want to extend it by introducing a new method, you’re facing the fact that you’re making the class even worse—longer, less cohesive, less readable, less maintainable, etc. You have a feeling that you’re digging into something dirty and that there is no hope to make it cleaner, ever. I’m sure, you’re familiar with this feeling—most legacy applications look that way. They have huge multi-line “classes” (in reality, COBOL programs written in Java) that were inherited from a few generations of programmers before you. When you start, you’re full of energy, but after a few minutes of scrolling such a “class” you say—“screw it, it’s almost Saturday.”</p><aside class="youtube"> <div class="box"> YouTube video #EnhRgXrHCC4<div class="play"></div></div><div>How Immutability Helps in OOP (in Russian with English subtitles); 21 May 2016.</div></aside><p>Because the class is so big, there is no data hiding or encapsulation any more—33 variables are accessible by over 100 methods. What is hidden? This Email.java file in reality is a big, procedural 2000-line script, called a “class” by mistake. Nothing is hidden, once you cross the border of the class by calling one of its methods. After that, you have full access to all the data you may need. Why is this bad? Well, why do we need encapsulation in the first place? In order to protect one programmer from another, aka defensive programming. While I’m busy changing the subject of the MIME message, I want to be sure that I’m not interfered with by some other method’s activity, that is changing a sender and touching my subject by mistake. Encapsulation helps us narrow down the scope of the problem, while this Email class is doing exactly the opposite.</p><p>Because the class is so big, its unit testing is even more complicated than the class itself. Why? Because of multiple inter-dependencies between its methods and properties. In order to test setCharset() you have to prepare the entire object by calling a few other methods, then you have to call send() to make sure the message being sent actually uses the encoding you specified. Thus, in order to test a one-line method setCharset() you run the entire integration testing scenario of sending a full MIME message through SMTP. Obviously, if something gets changed in one of the methods, almost every test method will be affected. In other words, tests are very fragile, unreliable and over-complicated.</p><p>I can go on and on with this “because the class is so big,” but I think it is obvious that a small, cohesive class is always better than a big one. It is obvious to me, to you, and to any object-oriented programmer. But why is it not so obvious to the developers of Apache Commons Email? I don’t think they are stupid or un-educated. What is it then?</p><h2 id="how-and-why-did-it-happen">How and Why Did It Happen?</h2><p>This is how it always happens. You start to design a class as something cohesive, solid, and small. Your intentions are very positive. Very soon you realize that there is something else that this class has to do. Then, something else. Then, even more.</p><p>The best way to make your class more and more powerful is by adding setters that inject configuration parameters into the class so that it can process them inside, isn’t it?</p><aside class="youtube"> <div class="box"> YouTube video #p7m7_iiqaHI<div class="play"></div></div><div>How Much Immutability Is Enough?; 19 May 2016.</div></aside><p>This is the root cause of the problem! The root cause is our ability to insert data into mutable objects via configuration methods, also known as “setters.” When an object is mutable and allows us to add setters whenever we want, we will do it without limits.</p><p>Let me put it this way—mutable classes tend to grow in size and lose cohesiveness.</p><p>If commons-email authors made this Email class immutable in the beginning, they wouldn’t have been able to add so many methods into it and encapsulate so many properties. They wouldn’t be able to turn it into a monster. Why? Because an immutable object only accepts a state through a constructor. Can you imagine a 33-argument constructor? Of course, not.</p><p>When you make your class immutable in the first place, you are forced to keep it cohesive, small, solid and robust. Because you can’t encapsulate too much and you can’t modify what’s encapsulated. Just two or three arguments of a constructor and you’re done.</p><h2 id="how-did-i-design-an-immutable-email">How Did I Design An Immutable Email?</h2>
    badge
    <p>When I was designing jcabi-email I started with a small and simple class: Postman. Well, it is an interface, since I never make interface-less classes. So, Postman is… a post man. He is delivering messages to other people. First, I created a default version of it (I omit the ctor, for the sake of brevity):</p>
    <pre>import javax.mail.Message; @Immutable class Postman.Default implements Postman { private final String host; private final int port; private final String user; private final String password; @Override void send(Message msg) { // create SMTP session // create transport // transport.connect(this.host, this.port, etc.) // transport.send(msg) // transport.close(); } }</pre>
    <p>Good start, it works. What now? Well, the Message is difficult to construct. It is a complex class from JDK that requires some manipulations before it can become a nice HTML email. So I created an envelope, which will build this complex object for me (pay attention, both Postman and Envelope are immutable and annotated with @Immutable from jcabi-aspects):</p>
    <pre>@Immutable interface Envelope { Message unwrap(); }</pre>
    <p>I also refactor the Postman to accept an envelope, not a message:</p>
    <pre>@Immutable interface Postman { void send(Envelope env); }</pre>
    <p>So far, so good. Now let’s try to create a simple implementation of Envelope:</p>
    <pre>@Immutable class MIME implements Envelope { @Override public Message unwrap() { return new MimeMessage( Session.getDefaultInstance(new Properties()) ); } }</pre>
    <p>It works, but it does nothing useful yet. It only creates an absolutely empty MIME message and returns it. How about adding a subject to it and both To: and From: addresses (pay attention, MIME class is also immutable):</p>
    <pre>@Immutable class Envelope.MIME implements Envelope { private final String subject; private final String from; private final Array<String> to; public MIME(String subj, String sender, Iterable<String> rcpts) { this.subject = subj; this.from = sender; this.to = new Array<String>(rcpts); } @Override public Message unwrap() { Message msg = new MimeMessage( Session.getDefaultInstance(new Properties()) ); msg.setSubject(this.subject); msg.setFrom(new InternetAddress(this.from)); for (String email : this.to) { msg.setRecipient( Message.RecipientType.TO, new InternetAddress(email) ); } return msg; } }</pre>
    <p>Looks correct and it works. But it is still too primitive. How about CC: and BCC:? What about email text? How about PDF enclosures? What if I want to specify the encoding of the message? What about Reply-To?</p><p>Can I add all these parameters to the constructor? Remember, the class is immutable and I can’t introduce the setReplyTo() method. I have to pass the replyTo argument into its constructor. It’s impossible, because the constructor will have too many arguments, and nobody will be able to use it.</p><p>So, what do I do?</p><p>Well, I started to think: how can we break the concept of an “envelope” into smaller concepts—and this what I invented. Like a real-life envelope, my MIME object will have stamps. Stamps will be responsible for configuring an object Message (again, Stamp is immutable, as well as all its implementers):</p>
    <pre>@Immutable interface Stamp { void attach(Message message); }</pre>
    <p>Now, I can simplify my MIME class to the following:</p>
    <pre>@Immutable class Envelope.MIME implements Envelope { private final Array<Stamp> stamps; public MIME(Iterable<Stamp> stmps) { this.stamps = new Array<Stamp>(stmps); } @Override public Message unwrap() { Message msg = new MimeMessage( Session.getDefaultInstance(new Properties()) ); for (Stamp stamp : this.stamps) { stamp.attach(msg); } return msg; } }</pre>
    <p>Now, I will create stamps for the subject, for To:, for From:, for CC:, for BCC:, etc. As many stamps as I like. The class MIME will stay the same—small, cohesive, readable, solid, etc.</p><p>What is important here is why I made the decision to refactor while the class was relatively small. Indeed, I started to worry about these stamp classes when my MIME class was just 25 lines in size.</p><p>That is exactly the point of this article—immutability forces you to design small and cohesive objects.</p><p>Without immutability, I would have gone the same direction as commons-email. My MIME class would grow in size and sooner or later would become as big as Email from commons-email. The only thing that stopped me was the necessity to refactor it, because I wasn’t able to pass all arguments through a constructor.</p><p>Without immutability, I wouldn’t have had that motivator and I would have done what Apache developers did with commons-email—bloat the class and turn it into an unmaintainable monster.</p><p>That’s jcabi-email. I hope this example was illustrative enough and that you will start writing cleaner code with immutable objects.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> What Does a Software Architect Do? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/10/12/who-is-software-architect.html>12 Best</li> <li /2014/10/12/who-is-software-architect.html>All 292</li> <li /2014/10/12/who-is-software-architect.html>Webinars</li> <li /2014/10/12/who-is-software-architect.html>Talks</li> <li /2014/10/12/who-is-software-architect.html>Books</li> <li /2014/10/12/who-is-software-architect.html>Papers</li> <li /2014/10/12/who-is-software-architect.html>Pets</li> <li /2014/10/12/who-is-software-architect.html class=”highlighted”>Trainings</li> <li /2014/10/12/who-is-software-architect.html>Award</li> <li /2014/10/12/who-is-software-architect.html>Testimonials</li> <li /2014/10/12/who-is-software-architect.html>Shift-M</li> <li /2014/10/12/who-is-software-architect.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">What Does a Software Architect Do?</h1><aside class='book'>book coverRead more about this subject in Section 2
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Japanese</li> <li>add yours!</li></ul><p class="unprintable"><p>Do you have a software architect in your project? Do you need one? Well, most agile teams do not define such a role explicitly and work in a democratic mode. Every important technical decision is discussed with the entire team, and the most voted for solution wins. When such a team eventually decides to put a “software architect” badge on someone’s t-shirt, the most reputable programmer gets it.</p>
    Jackie Brown (1997) by Quentin Tarantino<figcaption id="f41988de">Jackie Brown (1997) by Quentin Tarantino</figcaption>
    <p>The badge rarely changes his responsibilities, though. After all, the team stays the same and enjoys having technical discussions together, involving everyone. In the end, a software architect is more of a status than a role with explicitly defined responsibilities. It is a sign of respect, paid by other team players to the oldest and the most authoritative one among them. Right?</p><aside class="youtube"> <div class="box"> YouTube video #0fuEgmibJc4<div class="play"></div></div><div>Who Is a Software Architect?; 13 April 2015.</div></aside><p>Absolutely wrong!</p><p>Obviously, an architect is usually someone who has the most knowledge, skills, experience, and authority. Of course, an architect usually knows more than others and is able to communicate his knowledge with diplomacy and pedagogy when required. An architect is usually one of the smartest guys on the team.</p><aside class="quote">An architect is the one who takes the blame for the quality</aside><p>This is not, however, what makes him/her an architect.</p><p>And this is not what the team needs. My definition of a software architect is this:</p><p>An architect is the one who takes the blame for the quality.</p><aside class="youtube"> <div class="box"> YouTube video #PNSezrlemsY<div class="play"></div></div><div>Hacker vs Designer Mentality; 13 April 2015.</div></aside><p>You can replace “blame” with accountability or responsibility. Although, I prefer to use “blame,” because it much better emphasizes the fact that every quality issue in the product under development is a personal fault of the architect. Of course, together with the blame he also takes all the credit from happy customers, when the quality is good.</p><p>This is what the team needs—someone personally responsible for the quality of the software being developed.</p><aside class="quote">The job of the PM is to make sure that every technical decision the architect makes is not doubted by anyone</aside><p>How this guy will delegate this responsibility to others is his job. Whether he will use his knowledge and skills, or quality control tools, or unit testing frameworks, or authority, or coaching, or corporal punishment—it’s his business. A project manager delegates quality control to the software architect, and it is up to the software architect how to delegate it further.</p><p>The role of a software architect is crucial for every project, even if there are just two coders working at the same desk. One of them has to be the architect.</p><p>An ideal architect has all the merits mentioned above. He listens to everybody and takes their opinions into account. He is a good coach and a teacher, with a lot of patience. He is an effective communicator and negotiator. He is a diplomat. And he is an expert in the technical domain.</p><p>But, even if he doesn’t have all these merits, his decision is always final.</p><p>And this is the job of the project manager, to make sure that every technical decision the architect makes is not doubted by anyone. This is what delegation is all about—responsibility should always come with power.</p><aside class="youtube"> <div class="box"> YouTube video #AvVQ5NjS_Nk<div class="play"></div></div><div>Who is a Software Architect? (webinar #13); 13 April 2016.</div></aside><p>As a project manager, you should regularly evaluate the results of your architect. Remember, the quality of the product your team is working on is his personal (!) responsibility. Any problems you see are his problems. Don’t be afraid to blame him and punish him. But, always remember that in order to make your punishments productive you should give your architect full power in his actions. Let me reiterate: his decisions should be final.</p><p>If you, as a project manager, are not happy with the quality of the product and the architect doesn’t improve the situation, replace him. Downgrade him to a programmer and promote one of the programmers to an architect. But always remember that there can only be one architect in the team, and that his decisions are final.</p><p>That’s the only way of having a chance of building a perfect product.</p><blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Does your team have an official role of a Software Architect, who has enough authority to make technical decisions alone? #codeahead</p>— Yegor Bugayenko (@yegor256) May 13, 2018</blockquote> </p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Do you have a software architect in your project? Do you need one? Well, most agile teams do not define such a role explicitly and work in a democratic mode. Every important technical decision is discussed with the entire team, and the most voted for solution wins. When such a team eventually decides to put a “software architect” badge on someone’s t-shirt, the most reputable programmer gets it.</p>
    Jackie Brown (1997) by Quentin Tarantino<figcaption id="f41988de">Jackie Brown (1997) by Quentin Tarantino</figcaption>
    <p>The badge rarely changes his responsibilities, though. After all, the team stays the same and enjoys having technical discussions together, involving everyone. In the end, a software architect is more of a status than a role with explicitly defined responsibilities. It is a sign of respect, paid by other team players to the oldest and the most authoritative one among them. Right?</p><aside class="youtube"> <div class="box"> YouTube video #0fuEgmibJc4<div class="play"></div></div><div>Who Is a Software Architect?; 13 April 2015.</div></aside><p>Absolutely wrong!</p><p>Obviously, an architect is usually someone who has the most knowledge, skills, experience, and authority. Of course, an architect usually knows more than others and is able to communicate his knowledge with diplomacy and pedagogy when required. An architect is usually one of the smartest guys on the team.</p><aside class="quote">An architect is the one who takes the blame for the quality</aside><p>This is not, however, what makes him/her an architect.</p><p>And this is not what the team needs. My definition of a software architect is this:</p><p>An architect is the one who takes the blame for the quality.</p><aside class="youtube"> <div class="box"> YouTube video #PNSezrlemsY<div class="play"></div></div><div>Hacker vs Designer Mentality; 13 April 2015.</div></aside><p>You can replace “blame” with accountability or responsibility. Although, I prefer to use “blame,” because it much better emphasizes the fact that every quality issue in the product under development is a personal fault of the architect. Of course, together with the blame he also takes all the credit from happy customers, when the quality is good.</p><p>This is what the team needs—someone personally responsible for the quality of the software being developed.</p><aside class="quote">The job of the PM is to make sure that every technical decision the architect makes is not doubted by anyone</aside><p>How this guy will delegate this responsibility to others is his job. Whether he will use his knowledge and skills, or quality control tools, or unit testing frameworks, or authority, or coaching, or corporal punishment—it’s his business. A project manager delegates quality control to the software architect, and it is up to the software architect how to delegate it further.</p><p>The role of a software architect is crucial for every project, even if there are just two coders working at the same desk. One of them has to be the architect.</p><p>An ideal architect has all the merits mentioned above. He listens to everybody and takes their opinions into account. He is a good coach and a teacher, with a lot of patience. He is an effective communicator and negotiator. He is a diplomat. And he is an expert in the technical domain.</p><p>But, even if he doesn’t have all these merits, his decision is always final.</p><p>And this is the job of the project manager, to make sure that every technical decision the architect makes is not doubted by anyone. This is what delegation is all about—responsibility should always come with power.</p><aside class="youtube"> <div class="box"> YouTube video #AvVQ5NjS_Nk<div class="play"></div></div><div>Who is a Software Architect? (webinar #13); 13 April 2016.</div></aside><p>As a project manager, you should regularly evaluate the results of your architect. Remember, the quality of the product your team is working on is his personal (!) responsibility. Any problems you see are his problems. Don’t be afraid to blame him and punish him. But, always remember that in order to make your punishments productive you should give your architect full power in his actions. Let me reiterate: his decisions should be final.</p><p>If you, as a project manager, are not happy with the quality of the product and the architect doesn’t improve the situation, replace him. Downgrade him to a programmer and promote one of the programmers to an architect. But always remember that there can only be one architect in the team, and that his decisions are final.</p><p>That’s the only way of having a chance of building a perfect product.</p><blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Does your team have an official role of a Software Architect, who has enough authority to make technical decisions alone? #codeahead</p>— Yegor Bugayenko (@yegor256) May 13, 2018</blockquote> </div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Continuous Integration is Dead </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/10/08/continuous-integration-is-dead.html>12 Best</li> <li /2014/10/08/continuous-integration-is-dead.html>All 292</li> <li /2014/10/08/continuous-integration-is-dead.html>Webinars</li> <li /2014/10/08/continuous-integration-is-dead.html>Talks</li> <li /2014/10/08/continuous-integration-is-dead.html>Books</li> <li /2014/10/08/continuous-integration-is-dead.html>Papers</li> <li /2014/10/08/continuous-integration-is-dead.html>Pets</li> <li /2014/10/08/continuous-integration-is-dead.html class=”highlighted”>Trainings</li> <li /2014/10/08/continuous-integration-is-dead.html>Award</li> <li /2014/10/08/continuous-integration-is-dead.html>Testimonials</li> <li /2014/10/08/continuous-integration-is-dead.html>Shift-M</li> <li /2014/10/08/continuous-integration-is-dead.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Continuous Integration is Dead</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>A few days ago, my article Why Continuous Integration Doesn’t Work was published at DevOps.com. Almost the same day I received a few strongly negative critiques on Twitter.</p><p>Here is my response to the un-asked question:</p><blockquote><p>Why the hell shouldn’t continuous integration work, being such a brilliant and popular idea?</p></blockquote><p>Even though I have some experience in this area, I won’t use it as an argument. I’ll try to rely only on logic instead.</p><p>BTW, my experience includes five years of using Apache Continuum, Hudson, CruiseControl, and Jenkins in over 50 open source and commercial projects. Besides that, a few years ago I created a hosted continuous integration service called fazend.com, renamed to rultor.com in 2013. Currently, I’m also an active user of Travis and AppVeyor.</p><h2 id="how-continuous-integration-should-work">How Continuous Integration Should Work</h2><aside class="youtube"> <div class="box"> YouTube video #3IXk5yEJMIs<div class="play"></div></div><div>Continuous Integration is Dead; 24 April 2015.</div></aside><p>The idea is simple and obvious. Every time you make a new commit to the master branch (or /trunk in Subversion), a continuous integration server (or service) attempts to build the entire product. “Build” means compile, unit test, integration test, quality analysis, etc.</p><p>The result is either “success” or “failure.” If it is a success, we say that “the build is clean.” If it is a failure, we say that “the build is broken.” The build usually gets broken because someone breaks it by committing new code that turns previously passing unit tests into failing ones.</p><p>This is the technical side of the problem. It always works. Well, it may have its problems, like hard-coded dependencies, lack of isolation between environments or parallel build collisions, but this article is not about those. If the application is well written and its unit tests are stable, continuous integration is easy. Technically.</p><aside class="youtube"> <div class="box"> YouTube video #gL4XwP-EBOg<div class="play"></div></div><div>Continuous Integration May Have Negative Effects; 20 April 2016.</div></aside><p>Let’s see the organizational side.</p><p>Continuous integration is not only a server that builds, but a management/organizational process that should “work.” Being a process that works means exactly what Jez Humble said in Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation, on page 55:</p><blockquote><p>Crucially, if the build fails, the development team stops whatever they are doing and fixes the problem immediately</p></blockquote><p>This is what doesn’t work and can’t work.</p><h2 id="who-needs-this">Who Needs This?</h2><p>As we see, continuous integration is about setting the entire development team on pause and fixing the broken build. Let me reiterate. Once the build is broken, everybody should focus on fixing it and making a commit that returns the build to the stable state.</p><p>Now, my question is—who, in an actively working team, may need this?</p><p>A product owner, who is interested in launching new features to the market as soon as possible? Or maybe a project manager, who is responsible for the deadlines? Or maybe programmers, who hate to fix bugs made by someone else, especially under pressure?</p><p>Who likes this continuous integration and who needs it?</p><p>Nobody.</p><h2 id="what-happens-in-reality">What Happens In Reality?</h2><p>I can tell you. I’ve seen it multiple times. The scenario is always the same. We just start to ignore that continuous integration build status. Either the build is clean or it is broken, and we continue to do what we were doing before.</p><p>We don’t stop and fix it, as Jez Humble recommends.</p><p>Instead, we ignore the information that’s coming from the continuous integration server.</p><p>Eventually, maybe tomorrow or on Monday, we’ll try to find some spare time and will try to fix the build. Only because we don’t like that red button on the dashboard and want to turn it into a green one.</p><h2 id="what-about-discipline">What About Discipline?</h2><aside class="youtube"> <div class="box"> YouTube video #Ht0JI41kA4I<div class="play"></div></div><div>Pre-flight Build Pitfalls; 10 May 2016.</div></aside><p>Yes, there is another side of this coin. We can try to enforce discipline in the team. We can make it a strict rule, that our build is always clean and whoever breaks it gets some sort of a punishment.</p><p>Try doing this and you will get a fear driven development. Programmers will be afraid of committing anything to the repository because they will know that if they cause a build failure they will have to apologize, at least.</p><p>A strict discipline (which I’m a big fan of) in this case only makes the situation worse. The entire development process slows down and programmers keep their code to themselves for as long as possible, to avoid possibly broken builds. When it’s time to commit, their changes are so massive that merging becomes very difficult and sometimes impossible.</p><p>As a result you get a lot of throw-away code, written by someone but never committed to master, because of that fear factor.</p><h2 id="ok-what-is-the-solution">OK, What Is The Solution?</h2><p>I wrote about it before; it is called read-only master branch.</p><p>It is simple—prohibit anyone from merging anything into master and create a script that anyone can call. The script will merge, test, and commit. The script will not make any exceptions. If any branch breaks at even one unit test, the entire branch will be rejected.</p><p>In other words: raise the red flag before the code gets into master.</p><p>This solves all problems.</p><p>First, the build is always clean. We simply can’t break it because nobody can commit unless his code keeps the build clean.</p><p>Second, there is no fear of breaking anything. Simply because you technically can’t do it. All you can do is get a negative response from a merging script. Then you fix your errors and tell the script to try again. Nobody sees these attempts, and you don’t need to apologize. Fear factor is gone.</p><p>BTW, try to use rultor.com to enforce this read-only master branch principle in your project.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>A few days ago, my article Why Continuous Integration Doesn’t Work was published at DevOps.com. Almost the same day I received a few strongly negative critiques on Twitter.</p><p>Here is my response to the un-asked question:</p><blockquote><p>Why the hell shouldn’t continuous integration work, being such a brilliant and popular idea?</p></blockquote><p>Even though I have some experience in this area, I won’t use it as an argument. I’ll try to rely only on logic instead.</p><p>BTW, my experience includes five years of using Apache Continuum, Hudson, CruiseControl, and Jenkins in over 50 open source and commercial projects. Besides that, a few years ago I created a hosted continuous integration service called fazend.com, renamed to rultor.com in 2013. Currently, I’m also an active user of Travis and AppVeyor.</p><h2 id="how-continuous-integration-should-work">How Continuous Integration Should Work</h2><aside class="youtube"> <div class="box"> YouTube video #3IXk5yEJMIs<div class="play"></div></div><div>Continuous Integration is Dead; 24 April 2015.</div></aside><p>The idea is simple and obvious. Every time you make a new commit to the master branch (or /trunk in Subversion), a continuous integration server (or service) attempts to build the entire product. “Build” means compile, unit test, integration test, quality analysis, etc.</p><p>The result is either “success” or “failure.” If it is a success, we say that “the build is clean.” If it is a failure, we say that “the build is broken.” The build usually gets broken because someone breaks it by committing new code that turns previously passing unit tests into failing ones.</p><p>This is the technical side of the problem. It always works. Well, it may have its problems, like hard-coded dependencies, lack of isolation between environments or parallel build collisions, but this article is not about those. If the application is well written and its unit tests are stable, continuous integration is easy. Technically.</p><aside class="youtube"> <div class="box"> YouTube video #gL4XwP-EBOg<div class="play"></div></div><div>Continuous Integration May Have Negative Effects; 20 April 2016.</div></aside><p>Let’s see the organizational side.</p><p>Continuous integration is not only a server that builds, but a management/organizational process that should “work.” Being a process that works means exactly what Jez Humble said in Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation, on page 55:</p><blockquote><p>Crucially, if the build fails, the development team stops whatever they are doing and fixes the problem immediately</p></blockquote><p>This is what doesn’t work and can’t work.</p><h2 id="who-needs-this">Who Needs This?</h2><p>As we see, continuous integration is about setting the entire development team on pause and fixing the broken build. Let me reiterate. Once the build is broken, everybody should focus on fixing it and making a commit that returns the build to the stable state.</p><p>Now, my question is—who, in an actively working team, may need this?</p><p>A product owner, who is interested in launching new features to the market as soon as possible? Or maybe a project manager, who is responsible for the deadlines? Or maybe programmers, who hate to fix bugs made by someone else, especially under pressure?</p><p>Who likes this continuous integration and who needs it?</p><p>Nobody.</p><h2 id="what-happens-in-reality">What Happens In Reality?</h2><p>I can tell you. I’ve seen it multiple times. The scenario is always the same. We just start to ignore that continuous integration build status. Either the build is clean or it is broken, and we continue to do what we were doing before.</p><p>We don’t stop and fix it, as Jez Humble recommends.</p><p>Instead, we ignore the information that’s coming from the continuous integration server.</p><p>Eventually, maybe tomorrow or on Monday, we’ll try to find some spare time and will try to fix the build. Only because we don’t like that red button on the dashboard and want to turn it into a green one.</p><h2 id="what-about-discipline">What About Discipline?</h2><aside class="youtube"> <div class="box"> YouTube video #Ht0JI41kA4I<div class="play"></div></div><div>Pre-flight Build Pitfalls; 10 May 2016.</div></aside><p>Yes, there is another side of this coin. We can try to enforce discipline in the team. We can make it a strict rule, that our build is always clean and whoever breaks it gets some sort of a punishment.</p><p>Try doing this and you will get a fear driven development. Programmers will be afraid of committing anything to the repository because they will know that if they cause a build failure they will have to apologize, at least.</p><p>A strict discipline (which I’m a big fan of) in this case only makes the situation worse. The entire development process slows down and programmers keep their code to themselves for as long as possible, to avoid possibly broken builds. When it’s time to commit, their changes are so massive that merging becomes very difficult and sometimes impossible.</p><p>As a result you get a lot of throw-away code, written by someone but never committed to master, because of that fear factor.</p><h2 id="ok-what-is-the-solution">OK, What Is The Solution?</h2><p>I wrote about it before; it is called read-only master branch.</p><p>It is simple—prohibit anyone from merging anything into master and create a script that anyone can call. The script will merge, test, and commit. The script will not make any exceptions. If any branch breaks at even one unit test, the entire branch will be rejected.</p><p>In other words: raise the red flag before the code gets into master.</p><p>This solves all problems.</p><p>First, the build is always clean. We simply can’t break it because nobody can commit unless his code keeps the build clean.</p><p>Second, there is no fear of breaking anything. Simply because you technically can’t do it. All you can do is get a negative response from a merging script. Then you fix your errors and tell the script to try again. Nobody sees these attempts, and you don’t need to apologize. Fear factor is gone.</p><p>BTW, try to use rultor.com to enforce this read-only master branch principle in your project.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Stop Chatting, Start Coding </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/10/07/stop-chatting-start-coding.html>12 Best</li> <li /2014/10/07/stop-chatting-start-coding.html>All 292</li> <li /2014/10/07/stop-chatting-start-coding.html>Webinars</li> <li /2014/10/07/stop-chatting-start-coding.html>Talks</li> <li /2014/10/07/stop-chatting-start-coding.html>Books</li> <li /2014/10/07/stop-chatting-start-coding.html>Papers</li> <li /2014/10/07/stop-chatting-start-coding.html>Pets</li> <li /2014/10/07/stop-chatting-start-coding.html class=”highlighted”>Trainings</li> <li /2014/10/07/stop-chatting-start-coding.html>Award</li> <li /2014/10/07/stop-chatting-start-coding.html>Testimonials</li> <li /2014/10/07/stop-chatting-start-coding.html>Shift-M</li> <li /2014/10/07/stop-chatting-start-coding.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Stop Chatting, Start Coding</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
    badge
    <p>The first principle of eXtremely Distributed Software Development (XDSD) states that “everyone gets paid for verified deliverables.” This literally means that, in order to get paid, every programmer has to write the code, commit it to the repository, pass a code review and make sure the code is merged into the destination branch. Only then, is his result appreciated and paid for.</p>
    Barton Fink (1991) by Joel Coen<figcaption id="8606fa0a">Barton Fink (1991) by Joel Coen</figcaption>
    <p>For most of my clients this already sounds extreme. They are used to a traditional scheme of paying per hour or per month. They immediately realize the benefits of XDSD, though, because for them this approach means that project funds are not wasted on activities that don’t produce results.</p><aside class="youtube"> <div class="box"> YouTube video #qRZYJGYdrwk<div class="play"></div></div><div>XDSD: management without meetings; 13 February 2016.</div></aside><p>But that’s not all.</p><p>This principle also means that nobody is paid for anything except tasks explicitly assigned to him/her. Thus, when a programmer has a question about current design, specification, configuration, etc.—nobody will be interested in answering it. Why not? Because there is no payment attached to this. Answering questions in Skype, Slack, or HipChat, or by email is something that is not appreciated in XDSD in any way. The project simply doesn’t pay for this activity. That’s why none of our programmers do this.</p><p>More about this philosophy here: It’s Not a School!</p><p>We don’t use any (I mean it!) informal communication channels in XDSD projects. We don’t do meetings or conference calls. We never discuss any technical issues on Skype or by phone.</p><aside class="quote">Every hour spent by a team member is traceable to the line of code produced.</aside><p>So, how do we resolve problems and share information?</p><p>We use task tracking systems for that. When a developer has a question, he submits it as a new “ticket.” The project manager then picks it up and assigns it to another developer, who is able to answer it. Then, the answer goes back through the tracking system or directly into the source code.</p><p>The “question ticket” gets closed when its author is satisfied with the answer. When the ticket is closed, those who answered it get paid.</p><p>Using this model, we significantly improve project communications, by making them clean and transparent. We also save a lot of project funds, since every hour spent by a team member is traceable to the line of code he produced.</p><aside class="youtube"> <div class="box"> YouTube video #LB_YLWhGrco<div class="play"></div></div><div>Meetings-free Programming; 1 April 2016.</div></aside><p>You can see how this happens in action, for example, in this ticket (the project is open source; that’s why all communications are open): jcabi/jcabi-github#731. One Java developer is having a problem with his Git repository. Apparently he did something wrong and couldn’t solve the problem by himself. He asked for help by submitting a new bug to the project. He was paid for the bug report. Then, another team member was assigned to help him. He did, through a number of suggestions and instructions. In the end, the problem was solved, and he was also paid for the solution. In total, the project spent 45 minutes, and the problem was solved.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
    badge
    <p>The first principle of eXtremely Distributed Software Development (XDSD) states that “everyone gets paid for verified deliverables.” This literally means that, in order to get paid, every programmer has to write the code, commit it to the repository, pass a code review and make sure the code is merged into the destination branch. Only then, is his result appreciated and paid for.</p>
    Barton Fink (1991) by Joel Coen<figcaption id="8606fa0a">Barton Fink (1991) by Joel Coen</figcaption>
    <p>For most of my clients this already sounds extreme. They are used to a traditional scheme of paying per hour or per month. They immediately realize the benefits of XDSD, though, because for them this approach means that project funds are not wasted on activities that don’t produce results.</p><aside class="youtube"> <div class="box"> YouTube video #qRZYJGYdrwk<div class="play"></div></div><div>XDSD: management without meetings; 13 February 2016.</div></aside><p>But that’s not all.</p><p>This principle also means that nobody is paid for anything except tasks explicitly assigned to him/her. Thus, when a programmer has a question about current design, specification, configuration, etc.—nobody will be interested in answering it. Why not? Because there is no payment attached to this. Answering questions in Skype, Slack, or HipChat, or by email is something that is not appreciated in XDSD in any way. The project simply doesn’t pay for this activity. That’s why none of our programmers do this.</p><p>More about this philosophy here: It’s Not a School!</p><p>We don’t use any (I mean it!) informal communication channels in XDSD projects. We don’t do meetings or conference calls. We never discuss any technical issues on Skype or by phone.</p><aside class="quote">Every hour spent by a team member is traceable to the line of code produced.</aside><p>So, how do we resolve problems and share information?</p><p>We use task tracking systems for that. When a developer has a question, he submits it as a new “ticket.” The project manager then picks it up and assigns it to another developer, who is able to answer it. Then, the answer goes back through the tracking system or directly into the source code.</p><p>The “question ticket” gets closed when its author is satisfied with the answer. When the ticket is closed, those who answered it get paid.</p><p>Using this model, we significantly improve project communications, by making them clean and transparent. We also save a lot of project funds, since every hour spent by a team member is traceable to the line of code he produced.</p><aside class="youtube"> <div class="box"> YouTube video #LB_YLWhGrco<div class="play"></div></div><div>Meetings-free Programming; 1 April 2016.</div></aside><p>You can see how this happens in action, for example, in this ticket (the project is open source; that’s why all communications are open): jcabi/jcabi-github#731. One Java developer is having a problem with his Git repository. Apparently he did something wrong and couldn’t solve the problem by himself. He asked for help by submitting a new bug to the project. He was paid for the bug report. Then, another team member was assigned to help him. He did, through a number of suggestions and instructions. In the end, the problem was solved, and he was also paid for the solution. In total, the project spent 45 minutes, and the problem was solved.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Project Lifecycle in Zerocracy </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/10/06/software-project-lifecycle.html>12 Best</li> <li /2014/10/06/software-project-lifecycle.html>All 292</li> <li /2014/10/06/software-project-lifecycle.html>Webinars</li> <li /2014/10/06/software-project-lifecycle.html>Talks</li> <li /2014/10/06/software-project-lifecycle.html>Books</li> <li /2014/10/06/software-project-lifecycle.html>Papers</li> <li /2014/10/06/software-project-lifecycle.html>Pets</li> <li /2014/10/06/software-project-lifecycle.html class=”highlighted”>Trainings</li> <li /2014/10/06/software-project-lifecycle.html>Award</li> <li /2014/10/06/software-project-lifecycle.html>Testimonials</li> <li /2014/10/06/software-project-lifecycle.html>Shift-M</li> <li /2014/10/06/software-project-lifecycle.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Project Lifecycle in Zerocracy</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>In addition to being a hands-on programmer, I’m also co-founder and CTO of Zerocracy, a custom software development company. I play the role of a technical and management leader in all projects we work with.</p>
    badge
    <p>I wrote this article for those who’re interested in hiring me and/or my team. This article will demonstrate what happens from day one until the end of the project, when you choose to work with us.</p><p>You will see below that our methods of software development seriously differ from what many other teams are using. I personally pay a lot of attention to quality of code and quality of the internal processes that connect our team.</p><p>There are four phases in every project I work with in Zerocracy:</p><ul> <li><p>Thinking. Here we’re trying to understand: What is the problem that the product is going to solve? We’re also investigating the product’s boundaries—who will work with the software (actors) and how will they work with it (user stories). Deliverables: specification. Duration: from 2 days up to 3 weeks. Participants: product owner, analyst(s), architect, project manager.</p></li> <li><p>Building. Here the software architect is creating a proof-of-concept (aka an MVP or prototype or a skeleton). It is a one-man job that is done almost without any interaction with anyone else. The architect builds the product according to the specification in a very limited time frame. The result will have multiple bugs and open ends, but it will implement the main user story. The architect also configures continuous integration and delivery pipelines. Deliverables: working software. Duration: 2-5 days. Participants: architect.</p></li> <li><p>Fixing. At this phase we are adding all the meat to the skeleton. This phase takes most of the time and budget and involves many participants. In some projects we invite up to 50 people to work, at the same time. Since we treat all inconsistencies as bugs, this phase is mostly about finding, reporting and fixing bugs, in order to stabilize the product and get it ready for market launch. We increment and release the software multiple times a day, preferably to its user champions. Deliverables: bug fixes via pull requests. Duration: from weeks to months. Participants: programmer(s), designer(s), tester(s), code reviewer(s), architect, project manager.</p></li> <li><p>Using. At this final phase we are launching the product to its end-users, and collecting their feedback (both positive and negative). Everything they are reporting back to us is being registered as a bug. Then, we categorize the bugs and fix them. This phase may take years, but it never involves active implementation of new features. Deliverables: bug fixes via pull requests. Duration: months. Participants: programmer(s), code reviewer(s), project manager.</p></li></ul><p>The biggest (i.e., longest and most expensive) phase is, of course, Fixing. It usually takes the majority of time (over 70%). However, the most important and risky phase is the first one—Thinking. A mistake made during Thinking will cost much more than a mistake made later.</p><h2 id="thinking">Thinking</h2>
    badge
    <p>Thinking is the first and the most important phase.</p><p>First, we give a name to the project and create a GitHub repository. We try to keep all our projects (both open source and commercial) in GitHub. Mostly because the platform is very popular, very powerful, and really cheap ($7/mo for a set of 5 private projects). We also keep all communication in the GitHub issue tracker.</p><p>Then, we create a simple half-page SRS document (Software Requirements Specification). Usually this is done right inside the source code, but sometimes in the GitHub README.md file. What’s important is that the document should be under version control. We will modify it during the course of the project, very intensively. The README.md should briefly identify main “actors” of the system and define the product scope.</p><p>Even though it is only half a page, the creation of this initial SRS document is the most important and the most expensive task in the entire project. We pay a lot of attention to this step. Usually this document is written by one of our system analysts in direct communication with the project sponsor. We can’t afford a mistake at this step.</p><p>Then, we invite a few new system analysts to the project. These guys are responsible for turning our initial README into a more complete and detailed specification. They start by asking questions, submitting them one by one as GitHub issues. Every question is addressed to the product owner. Using his/her answers, system analysts modify the README document. Sometimes we’re using Requs.</p><p>At the end of the Thinking phase we estimate the size of the project, in Hits of Code. Using this HoC metric, we can roughly estimate a budget.</p><h2 id="building">Building</h2>
    badge
    <p>This is a one-man job for an architect. Every project we work on has an architect who is personally responsible for the quality and technical decisions. We have a few brilliant engineers for this role.</p><p>The Building phase is rather straight forward. The architect has to implement the solution according to the README, in a few working days. No matter how big the idea and how massive the planning development, the architect still has to create (build from scratch!) the product in, say, three days.</p><p>Besides building the software itself, the architect has to configure all basic DevOps processes, including: 1) automated testing and quality control, 2) deploying and releasing pipelines, 3) repository of artifacts, 4) continuous integration service, etc.</p><p>The result of this phase is a working software package, deployable to its destination and available for testers. Technical quality requirements are also defined at this phase.</p><p>More about the Building phase here: Nine Steps to Start a Software Project</p><h2 id="fixing">Fixing</h2>
    badge
    <p>Now it’s time to build a distributed team of programmers. First, we invite those who’ve worked on other projects and have already have proven their quality. Very often we invite new people, finding them through StackOverflow, GitHub, Upwork, and other sources. An average team size of an average project is 15-25 programmers.</p><p>At this phase, we understand any inconsistency as a bug. If something is not clear in the documentation, or if something can be refactored for better readability, or if a function can be improved for higher performance—it is a bug to us. And bugs are welcome in our projects. We encourage everybody to report as many bugs as possible. This is how we achieve high quality.</p><p>That is why the phase is called Fixing, after all. We are reporting bugs and fixing them. Hundreds of bugs. Sometimes thousands. The product grows in front of our very eyes, because after every bug fix we re-deploy the entire product to the production platform.</p><p>Every bug is reported, classified, discussed, and fixed in its own GitHub ticket and its own Git branch. We never allow anyone to just commit to the master branch—all changes must pass through our quality controls and be merged into master by rultor.com, our merging bot.</p><p>Also important to mention is that all communications with the product owner and between programmers happen only through GitHub issues. We never use any chats, Skype, emails or conferencing software. We communicate only through tickets and comments in GitHub.</p><h2 id="using">Using</h2>
    badge
    <p>This is the final phase and it can take quite a long time. By now, the product is ready and is launched to the market. But we still receive bug reports and feature request from the product owner, and we still fix them through the same process flow as in the Fixing phase.</p><p>We try to keep this phase as quiet as possible, in terms of the amount of bugs reported and fixed. Thanks to our intensive and pro-active bug finding and fixing in the previous phase, we usually have very few problems at the Using phase.</p><p>And big feature requests? At this phase, we usually try to convert them into new projects and develop them separately, starting again from Thinking.</p><p>BTW, the illustrations you see above are made by Bárbara Lopes.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>In addition to being a hands-on programmer, I’m also co-founder and CTO of Zerocracy, a custom software development company. I play the role of a technical and management leader in all projects we work with.</p>
    badge
    <p>I wrote this article for those who’re interested in hiring me and/or my team. This article will demonstrate what happens from day one until the end of the project, when you choose to work with us.</p><p>You will see below that our methods of software development seriously differ from what many other teams are using. I personally pay a lot of attention to quality of code and quality of the internal processes that connect our team.</p><p>There are four phases in every project I work with in Zerocracy:</p><ul> <li><p>Thinking. Here we’re trying to understand: What is the problem that the product is going to solve? We’re also investigating the product’s boundaries—who will work with the software (actors) and how will they work with it (user stories). Deliverables: specification. Duration: from 2 days up to 3 weeks. Participants: product owner, analyst(s), architect, project manager.</p></li> <li><p>Building. Here the software architect is creating a proof-of-concept (aka an MVP or prototype or a skeleton). It is a one-man job that is done almost without any interaction with anyone else. The architect builds the product according to the specification in a very limited time frame. The result will have multiple bugs and open ends, but it will implement the main user story. The architect also configures continuous integration and delivery pipelines. Deliverables: working software. Duration: 2-5 days. Participants: architect.</p></li> <li><p>Fixing. At this phase we are adding all the meat to the skeleton. This phase takes most of the time and budget and involves many participants. In some projects we invite up to 50 people to work, at the same time. Since we treat all inconsistencies as bugs, this phase is mostly about finding, reporting and fixing bugs, in order to stabilize the product and get it ready for market launch. We increment and release the software multiple times a day, preferably to its user champions. Deliverables: bug fixes via pull requests. Duration: from weeks to months. Participants: programmer(s), designer(s), tester(s), code reviewer(s), architect, project manager.</p></li> <li><p>Using. At this final phase we are launching the product to its end-users, and collecting their feedback (both positive and negative). Everything they are reporting back to us is being registered as a bug. Then, we categorize the bugs and fix them. This phase may take years, but it never involves active implementation of new features. Deliverables: bug fixes via pull requests. Duration: months. Participants: programmer(s), code reviewer(s), project manager.</p></li></ul><p>The biggest (i.e., longest and most expensive) phase is, of course, Fixing. It usually takes the majority of time (over 70%). However, the most important and risky phase is the first one—Thinking. A mistake made during Thinking will cost much more than a mistake made later.</p><h2 id="thinking">Thinking</h2>
    badge
    <p>Thinking is the first and the most important phase.</p><p>First, we give a name to the project and create a GitHub repository. We try to keep all our projects (both open source and commercial) in GitHub. Mostly because the platform is very popular, very powerful, and really cheap ($7/mo for a set of 5 private projects). We also keep all communication in the GitHub issue tracker.</p><p>Then, we create a simple half-page SRS document (Software Requirements Specification). Usually this is done right inside the source code, but sometimes in the GitHub README.md file. What’s important is that the document should be under version control. We will modify it during the course of the project, very intensively. The README.md should briefly identify main “actors” of the system and define the product scope.</p><p>Even though it is only half a page, the creation of this initial SRS document is the most important and the most expensive task in the entire project. We pay a lot of attention to this step. Usually this document is written by one of our system analysts in direct communication with the project sponsor. We can’t afford a mistake at this step.</p><p>Then, we invite a few new system analysts to the project. These guys are responsible for turning our initial README into a more complete and detailed specification. They start by asking questions, submitting them one by one as GitHub issues. Every question is addressed to the product owner. Using his/her answers, system analysts modify the README document. Sometimes we’re using Requs.</p><p>At the end of the Thinking phase we estimate the size of the project, in Hits of Code. Using this HoC metric, we can roughly estimate a budget.</p><h2 id="building">Building</h2>
    badge
    <p>This is a one-man job for an architect. Every project we work on has an architect who is personally responsible for the quality and technical decisions. We have a few brilliant engineers for this role.</p><p>The Building phase is rather straight forward. The architect has to implement the solution according to the README, in a few working days. No matter how big the idea and how massive the planning development, the architect still has to create (build from scratch!) the product in, say, three days.</p><p>Besides building the software itself, the architect has to configure all basic DevOps processes, including: 1) automated testing and quality control, 2) deploying and releasing pipelines, 3) repository of artifacts, 4) continuous integration service, etc.</p><p>The result of this phase is a working software package, deployable to its destination and available for testers. Technical quality requirements are also defined at this phase.</p><p>More about the Building phase here: Nine Steps to Start a Software Project</p><h2 id="fixing">Fixing</h2>
    badge
    <p>Now it’s time to build a distributed team of programmers. First, we invite those who’ve worked on other projects and have already have proven their quality. Very often we invite new people, finding them through StackOverflow, GitHub, Upwork, and other sources. An average team size of an average project is 15-25 programmers.</p><p>At this phase, we understand any inconsistency as a bug. If something is not clear in the documentation, or if something can be refactored for better readability, or if a function can be improved for higher performance—it is a bug to us. And bugs are welcome in our projects. We encourage everybody to report as many bugs as possible. This is how we achieve high quality.</p><p>That is why the phase is called Fixing, after all. We are reporting bugs and fixing them. Hundreds of bugs. Sometimes thousands. The product grows in front of our very eyes, because after every bug fix we re-deploy the entire product to the production platform.</p><p>Every bug is reported, classified, discussed, and fixed in its own GitHub ticket and its own Git branch. We never allow anyone to just commit to the master branch—all changes must pass through our quality controls and be merged into master by rultor.com, our merging bot.</p><p>Also important to mention is that all communications with the product owner and between programmers happen only through GitHub issues. We never use any chats, Skype, emails or conferencing software. We communicate only through tickets and comments in GitHub.</p><h2 id="using">Using</h2>
    badge
    <p>This is the final phase and it can take quite a long time. By now, the product is ready and is launched to the market. But we still receive bug reports and feature request from the product owner, and we still fix them through the same process flow as in the Fixing phase.</p><p>We try to keep this phase as quiet as possible, in terms of the amount of bugs reported and fixed. Thanks to our intensive and pro-active bug finding and fixing in the previous phase, we usually have very few problems at the Using phase.</p><p>And big feature requests? At this phase, we usually try to convert them into new projects and develop them separately, starting again from Thinking.</p><p>BTW, the illustrations you see above are made by Bárbara Lopes.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Best Hosted Continuous Integration Services for a Private Repository </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>12 Best</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>All 292</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Webinars</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Talks</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Books</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Papers</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Pets</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html class=”highlighted”>Trainings</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Award</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Testimonials</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Shift-M</li> <li /2014/10/05/ten-hosted-continuous-integration-services.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Best Hosted Continuous Integration Services for a Private Repository</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Every project I’m working with starts with a setup of continuous integration pipeline. I’m a big fan of cloud services, that’s why I was always using Travis. A few of my clients questioned this choice recently, mostly because of the price. So I decided to make a brief analysis of the market.</p><p>I configured Rultor, an open source project, in every CI service I managed to find. All of them are free for open source projects. All of them are hosted and do not require any server installation Here they are, in order of my personal preference (first four are the best and highly recommended):</p><table> <colgroup> <col class="x-col1" /> <col class="x-col2" /> <col class="x-colX" /> <col class="x-colX" /> <col class="x-colX" /> <col class="x-colX" /> <col class="x-colX" /> </colgroup> <thead> <tr class="x-head"><td></td><td class="x-bottom x-right">Minimum price</td><td class="x-vertical"><div>Linux1</div></td><td class="x-vertical"><div>Windows2</div></td><td class="x-vertical"><div>MacOS3</div></td><td class="x-vertical"><div>Pull requests4</div></td><td class="x-vertical"><div>Log compress5</div></td><td class="x-vertical"><div>Docker6</div></td><td class="x-bottom">Build</td></tr> </thead> <tbody> <tr><td>Shippable☺</td><td class="x-right">free (!)</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td> badge</td></tr> <tr><td>Travis</td><td class="x-right">$69/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td> badge</td></tr> <tr><td>AppVeyor</td><td class="x-right">$39/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">—</td><td> badge</td></tr> <tr><td>Wercker</td><td class="x-right">$350/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td> badge</td></tr> <tr><td colspan="9" class="x-hr"></td></tr> <tr><td>SemaphoreApp</td><td class="x-right">$29/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td></tr> <tr><td>Snap-CI☺</td><td class="x-right">$30/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center"></td></tr> <tr><td>Codeship☺</td><td class="x-right">$49/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center"></td><td class="center"></td></tr> <tr><td>CircleCI☺</td><td class="x-right">$19/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td></tr> <tr><td>SonoLabs</td><td class="x-right">$15/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center"></td></tr> <tr><td>DeployBot</td><td class="x-right">$15/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">?</td><td class="center"></td></tr> <tr><td>Vexor</td><td class="x-right">¢90/hr</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">?</td><td class="center"></td></tr> <tr><td>GreenHouseCI</td><td class="x-right">$49/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">?</td><td class="center"></td></tr> </tbody> </table><p>If you know any other good continuous integration services, email me, I’ll review and add them to this list. BTW, here is a “full” list of continuous integration software and services.</p><p>By the way, a few platforms from this list contacted me and asked to review them again. Some even offered me money to put them higher in the list (kidding). Anyway, it’s up to you to decide whether it’s a good sign or not (I think it’s good, they care about their PR). I marked them in the list with ☺ emoji.</p><h2 id="best-four">Best Four</h2>
    badge
    <p>Shippable was easy to configure since it understands .travis.yml out of the box. The user interface is easy to navigate since it doesn’t have “settings” page at all (or I didn’t find it). Everything is configured via shippable.yml file in the repository. The service looks stable and robust, no complains so far. What is especially cool about them is that they allow you to build in a Docker container.</p>
    badge
    <p>Travis is the best platform I’ve seen so far. Mostly because it is the most popular. Perfectly integrates with GitHub and has proper documentation. One important downside is the price of $129 per month. “With this money you can get a dedicated EC2 instance and install Jenkins there”—some of my clients say. I strongly disagree, since Jenkins will require a 24x7 administration, which costs way more than $129, but it’s always difficult to explain.</p>
    badge
    <p>Wercker is a European product from Amsterdam, which is still in beta and that’s why free for all projects. The platform looks very promising. It is still free for private repositories and is backed up by investments. They also have an interesting concept of build “boxes,” which can be pre-configured similar to Docker containers. It works rather stable for the last few months, no complains so far.</p>
    badge
    <p>AppVeyor is the only one that runs Windows builds. Even though I’m working mostly with Java and Ruby, which are expected to be platform independent, they very often appear to be exactly the opposite. When your build succeeds on Linux, there is almost no guarantee it will pass on Windows or Mac. I’m planning to use AppVeyor in every project, in combination with some other CI service. Here is how I integrate Maven builds with AppVeyor.</p><h2 id="others">Others</h2>
    badge
    <p>SemaphoreApp is easy to configure and work with. It makes an impression of a light-weight system, which I generally appreciate. As a downside, they don’t have any Maven pre-installed have an old version of Maven, but this was solved easily with a short custom script that downloads and unpacks the latest Maven. Another downside is that they are not configurable through a file (like .travis.yml)—you should do everything through a UI. They also support caching between builds.</p>
    badge
    <p>Snap-CI is a product of ThoughtWorks, an author of Go, an open source continuous integration server. It looks a bit more complicated than others, giving you an ability to define “stages” and combine them into pipelines. I’m not sure yet how these mechanisms may help in small and medium size projects we’re mostly working with, but they look “cool.” There is also a very unfortunate limitation of 2Gb RAM per build—some of my Java projects fail because of that. Besides that, they don’t give full access to the build server, for example we can’t modify anything in /etc—it is a show-stopper for us.</p><p>Codeship works fine, but their web UI looks a bit out-dated. Besides that, they promise to work with pull requests, but I didn’t manage to configure them. They simply don’t notify our pull requests in GitHub, even though they build them. Maybe I’ll find a way, so far it’s not clear.</p>
    badge
    <p>CircleCI I still don’t know why my build fails there. Really difficult to configure and understand what’s going on. Trying to figure it out…</p>
    badge
    <p>SolanoLabs looks rather immature and difficult to configure. They don’t even support automatic GitHub hook configuration when new repository is added. However, their sales spams me rather aggressively :)</p>
    badge
    <p>Hosted-CI is for iOS/OSX only. They don’t give anything for free, even for open source projects. I didn’t have a chance to test them yet.</p>
    badge
    <p>CloudBees is basically a hosted Jenkins. I don’t really like Jenkins, that’s why can’t recommend this platform.</p>
    badge
    <p>DeployBot doesn’t even allow me to login via GitHub, huh? They seem to be more “deployment” oriented, not just continuous integration.</p>
    badge
    <p>Vexor looks nice and offers a rather unique billing model—they charge per build, not per month. I would definitely recommend to give it a try. I couldn’t make it work though…</p>
    badge
    <p>GreenHouseCI is a CI platform for mobile apps (iOS, Android, etc.) Seems to be interesting, I just don’t have a full scale mobile app to test it against.</p><hr /><p>gitlab-ci: will review soon</p><p>coverity.com: will review it soon and add to the list.</p><p>buddy.works: will review soon.</p><p>AWS Code Build and AWS Code Deploy: will review soon.</p><p>Ship.io is dead (as of 20-Sep-2016).</p><p>ZeroCI.com is dead (as of 28-Aug-2016).</p><p>Drone.io is not hosted any more, but is open source (as of 23-Jan-2017).</p><p>Hosted-ci doesn’t look alive (as of 16-Apr-2017).</p><p>Magnum-CI.com doesn’t look alive (as of 30-May-2017).</p><hr /><p>BTW, if you don’t like the idea of keeping continuous integration in cloud, consider these on-premise software packages (in order or preference): Jenkins, TeamCity, Go, Strider, BuildBot.</p><p>Keep in mind that no matter how good and expensive your continuous integration service is, it won’t help you unless you make your master branch read-only.</p><hr /><p>1 This means that the platform can build your repo in Linux environment. Almost all of them do that by default, unless you configure them otherwise.
    2 Some of them can build on Windows platform.
    3 MacOS support means that an Objective-C/Swift product can be built there.
    4 I mean GitHub pull request support here. Some of them can be integrated with GitHub and will build pull requests before they are merged. Build status will be visible in GitHub. A pretty convenient feature.
    5 Logs compression is a critical feature, at least for me. Most of my logs are from Maven and without col -b they look too long and unreadable.
    6 Looks like Docker containers must be supported by all of them, but unfortunately it’s not the case. Ideally, all builds should run in containers.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Every project I’m working with starts with a setup of continuous integration pipeline. I’m a big fan of cloud services, that’s why I was always using Travis. A few of my clients questioned this choice recently, mostly because of the price. So I decided to make a brief analysis of the market.</p><p>I configured Rultor, an open source project, in every CI service I managed to find. All of them are free for open source projects. All of them are hosted and do not require any server installation Here they are, in order of my personal preference (first four are the best and highly recommended):</p><table> <colgroup> <col class="x-col1" /> <col class="x-col2" /> <col class="x-colX" /> <col class="x-colX" /> <col class="x-colX" /> <col class="x-colX" /> <col class="x-colX" /> </colgroup> <thead> <tr class="x-head"><td></td><td class="x-bottom x-right">Minimum price</td><td class="x-vertical"><div>Linux1</div></td><td class="x-vertical"><div>Windows2</div></td><td class="x-vertical"><div>MacOS3</div></td><td class="x-vertical"><div>Pull requests4</div></td><td class="x-vertical"><div>Log compress5</div></td><td class="x-vertical"><div>Docker6</div></td><td class="x-bottom">Build</td></tr> </thead> <tbody> <tr><td>Shippable☺</td><td class="x-right">free (!)</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td> badge</td></tr> <tr><td>Travis</td><td class="x-right">$69/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td> badge</td></tr> <tr><td>AppVeyor</td><td class="x-right">$39/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">—</td><td> badge</td></tr> <tr><td>Wercker</td><td class="x-right">$350/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td> badge</td></tr> <tr><td colspan="9" class="x-hr"></td></tr> <tr><td>SemaphoreApp</td><td class="x-right">$29/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td></tr> <tr><td>Snap-CI☺</td><td class="x-right">$30/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center"></td></tr> <tr><td>Codeship☺</td><td class="x-right">$49/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center"></td><td class="center"></td></tr> <tr><td>CircleCI☺</td><td class="x-right">$19/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td></tr> <tr><td>SonoLabs</td><td class="x-right">$15/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center"></td></tr> <tr><td>DeployBot</td><td class="x-right">$15/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">?</td><td class="center"></td></tr> <tr><td>Vexor</td><td class="x-right">¢90/hr</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">?</td><td class="center"></td></tr> <tr><td>GreenHouseCI</td><td class="x-right">$49/mo</td><td class="center"></td><td class="center"></td><td class="center"></td><td class="center">?</td><td class="center">?</td><td class="center"></td></tr> </tbody> </table><p>If you know any other good continuous integration services, email me, I’ll review and add them to this list. BTW, here is a “full” list of continuous integration software and services.</p><p>By the way, a few platforms from this list contacted me and asked to review them again. Some even offered me money to put them higher in the list (kidding). Anyway, it’s up to you to decide whether it’s a good sign or not (I think it’s good, they care about their PR). I marked them in the list with ☺ emoji.</p><h2 id="best-four">Best Four</h2>
    badge
    <p>Shippable was easy to configure since it understands .travis.yml out of the box. The user interface is easy to navigate since it doesn’t have “settings” page at all (or I didn’t find it). Everything is configured via shippable.yml file in the repository. The service looks stable and robust, no complains so far. What is especially cool about them is that they allow you to build in a Docker container.</p>
    badge
    <p>Travis is the best platform I’ve seen so far. Mostly because it is the most popular. Perfectly integrates with GitHub and has proper documentation. One important downside is the price of $129 per month. “With this money you can get a dedicated EC2 instance and install Jenkins there”—some of my clients say. I strongly disagree, since Jenkins will require a 24x7 administration, which costs way more than $129, but it’s always difficult to explain.</p>
    badge
    <p>Wercker is a European product from Amsterdam, which is still in beta and that’s why free for all projects. The platform looks very promising. It is still free for private repositories and is backed up by investments. They also have an interesting concept of build “boxes,” which can be pre-configured similar to Docker containers. It works rather stable for the last few months, no complains so far.</p>
    badge
    <p>AppVeyor is the only one that runs Windows builds. Even though I’m working mostly with Java and Ruby, which are expected to be platform independent, they very often appear to be exactly the opposite. When your build succeeds on Linux, there is almost no guarantee it will pass on Windows or Mac. I’m planning to use AppVeyor in every project, in combination with some other CI service. Here is how I integrate Maven builds with AppVeyor.</p><h2 id="others">Others</h2>
    badge
    <p>SemaphoreApp is easy to configure and work with. It makes an impression of a light-weight system, which I generally appreciate. As a downside, they don’t have any Maven pre-installed have an old version of Maven, but this was solved easily with a short custom script that downloads and unpacks the latest Maven. Another downside is that they are not configurable through a file (like .travis.yml)—you should do everything through a UI. They also support caching between builds.</p>
    badge
    <p>Snap-CI is a product of ThoughtWorks, an author of Go, an open source continuous integration server. It looks a bit more complicated than others, giving you an ability to define “stages” and combine them into pipelines. I’m not sure yet how these mechanisms may help in small and medium size projects we’re mostly working with, but they look “cool.” There is also a very unfortunate limitation of 2Gb RAM per build—some of my Java projects fail because of that. Besides that, they don’t give full access to the build server, for example we can’t modify anything in /etc—it is a show-stopper for us.</p><p>Codeship works fine, but their web UI looks a bit out-dated. Besides that, they promise to work with pull requests, but I didn’t manage to configure them. They simply don’t notify our pull requests in GitHub, even though they build them. Maybe I’ll find a way, so far it’s not clear.</p>
    badge
    <p>CircleCI I still don’t know why my build fails there. Really difficult to configure and understand what’s going on. Trying to figure it out…</p>
    badge
    <p>SolanoLabs looks rather immature and difficult to configure. They don’t even support automatic GitHub hook configuration when new repository is added. However, their sales spams me rather aggressively :)</p>
    badge
    <p>Hosted-CI is for iOS/OSX only. They don’t give anything for free, even for open source projects. I didn’t have a chance to test them yet.</p>
    badge
    <p>CloudBees is basically a hosted Jenkins. I don’t really like Jenkins, that’s why can’t recommend this platform.</p>
    badge
    <p>DeployBot doesn’t even allow me to login via GitHub, huh? They seem to be more “deployment” oriented, not just continuous integration.</p>
    badge
    <p>Vexor looks nice and offers a rather unique billing model—they charge per build, not per month. I would definitely recommend to give it a try. I couldn’t make it work though…</p>
    badge
    <p>GreenHouseCI is a CI platform for mobile apps (iOS, Android, etc.) Seems to be interesting, I just don’t have a full scale mobile app to test it against.</p><hr /><p>gitlab-ci: will review soon</p><p>coverity.com: will review it soon and add to the list.</p><p>buddy.works: will review soon.</p><p>AWS Code Build and AWS Code Deploy: will review soon.</p><p>Ship.io is dead (as of 20-Sep-2016).</p><p>ZeroCI.com is dead (as of 28-Aug-2016).</p><p>Drone.io is not hosted any more, but is open source (as of 23-Jan-2017).</p><p>Hosted-ci doesn’t look alive (as of 16-Apr-2017).</p><p>Magnum-CI.com doesn’t look alive (as of 30-May-2017).</p><hr /><p>BTW, if you don’t like the idea of keeping continuous integration in cloud, consider these on-premise software packages (in order or preference): Jenkins, TeamCity, Go, Strider, BuildBot.</p><p>Keep in mind that no matter how good and expensive your continuous integration service is, it won’t help you unless you make your master branch read-only.</p><hr /><p>1 This means that the platform can build your repo in Linux environment. Almost all of them do that by default, unless you configure them otherwise.
    2 Some of them can build on Windows platform.
    3 MacOS support means that an Objective-C/Swift product can be built there.
    4 I mean GitHub pull request support here. Some of them can be integrated with GitHub and will build pull requests before they are merged. Build status will be visible in GitHub. A pretty convenient feature.
    5 Logs compression is a critical feature, at least for me. Most of my logs are from Maven and without col -b they look too long and unreadable.
    6 Looks like Docker containers must be supported by all of them, but unfortunately it’s not the case. Ideally, all builds should run in containers.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Built-in Fake Objects </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/09/23/built-in-fake-objects.html>12 Best</li> <li /2014/09/23/built-in-fake-objects.html>All 292</li> <li /2014/09/23/built-in-fake-objects.html>Webinars</li> <li /2014/09/23/built-in-fake-objects.html>Talks</li> <li /2014/09/23/built-in-fake-objects.html>Books</li> <li /2014/09/23/built-in-fake-objects.html>Papers</li> <li /2014/09/23/built-in-fake-objects.html>Pets</li> <li /2014/09/23/built-in-fake-objects.html class=”highlighted”>Trainings</li> <li /2014/09/23/built-in-fake-objects.html>Award</li> <li /2014/09/23/built-in-fake-objects.html>Testimonials</li> <li /2014/09/23/built-in-fake-objects.html>Shift-M</li> <li /2014/09/23/built-in-fake-objects.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Built-in Fake Objects</h1><aside class='book'>book coverRead more about this subject in Section 2.8
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>While mock objects are perfect instruments for unit testing, mocking through mock frameworks may turn your unit tests into an unmaintainable mess. Thanks to them we often hear that “mocking is bad” and “mocking is evil.”</p><p>The root cause of this complexity is that our objects are too big. They have many methods and these methods return other objects, which also have methods. When we pass a mock version of such an object as a parameter, we should make sure that all of its methods return valid objects.</p><p>This leads to inevitable complexity, which turns unit tests to waste almost impossible to maintain.</p><h2 id="object-hierarchy">Object Hierarchy</h2><p>Take the Region interface from jcabi-dynamo as an example (this snippet and all others in this article are simplified, for the sake of brevity):</p>
    <pre>public interface Region { Table table(String name); }</pre>
    <p>Its table() method returns an instance of the Table interface, which has its own methods:</p>
    <pre>public interface Table { Frame frame(); Item put(Attributes attrs); Region region(); }</pre>
    <p>Interface Frame, returned by the frame() method, also has its own methods. And so on. In order to create a properly mocked instance of interface Region, one would normally create a dozen other mock objects. With Mockito it will look like this:</p>
    <pre>public void testMe() { // many more lines here... Frame frame = Mockito.mock(Frame.class); Mockito.doReturn(...).when(frame).iterator(); Table table = Mockito.mock(Table.class); Mockito.doReturn(frame).when(table).frame(); Region region = Mockito.mock(Region.class); Mockito.doReturn(table).when(region).table(Mockito.anyString()); }</pre>
    <p>And all of this is just a scaffolding before the actual testing.</p><h2 id="sample-use-case">Sample Use Case</h2><p>Let’s say, you’re developing a project that uses jcabi-dynamo for managing data in DynamoDB. Your class may look similar to this:</p>
    <pre>public class Employee { private final String name; private final Region region; public Employee(String empl, Region dynamo) { this.name = empl; this.region = dynamo; } public Integer salary() { return Integer.parseInt( this.region .table("employees") .frame() .where("name", this.name) .iterator() .next() .get("salary") .getN() ); } }</pre>
    <p>You can imagine how difficult it will be to unit test this class, using Mockito, for example. First, we have to mock the Region interface. Then, we have to mock a Table interface and make sure it is returned by the table() method. Then, we have to mock a Frame interface, etc.</p><aside class="youtube"> <div class="box"> YouTube video #l6MpCBzwDbg<div class="play"></div></div><div>What Fake Objects Are For? (webinar #8); 4 November 2015.</div></aside><p>The unit test will be much longer than the class itself. Besides that, its real purpose, which is to test the retrieval of an employee’s salary, will not be obvious to the reader.</p><p>Moreover, when we need to test a similar method of a similar class, we will need to restart this mocking from scratch. Again, multiple lines of code, which will look very similar to what we have already written.</p><h2 id="fake-classes">Fake Classes</h2><p>The solution is to create fake classes and ship them together with real classes. This is what jcabi-dynamo is doing. Just look at its JavaDoc. There is a package called com.jcabi.dynamo.mock that contains only fake classes, suitable only for unit testing.</p><p>Even though their sole purpose is to optimize unit testing, we ship them together with production code, in the same JAR package.</p><p>This is what a test will look like, when a fake class MkRegion is used:</p>
    <pre>public class EmployeeTest { public void canFetchSalaryFromDynamoDb() { Region region = new MkRegion( new H2Data().with( "employees", new String[] {"name"}, new String[] {"salary"} ) ); region.table("employees").put( new Attributes() .with("name", "Jeff") .with("salary", new AttributeValue().withN(50000)) ); Employee emp = new Employee("Jeff", region); assertThat(emp.salary(), equalTo(50000)); } }</pre>
    <p>This test looks obvious to me. First, we create a fake DynamoDB region, which works on top of H2Data storage (in-memory H2 database). The storage will be ready for a single employees table with a hash key name and a single salary attribute.</p><aside class="youtube"> <div class="box"> YouTube video #EDKbYVEInMU<div class="play"></div></div><div>Built-in Fake Objects; 10 November 2016.</div></aside><p>Then, we put a record into the table, with a hash Jeff and a salary 50000.</p><p>Finally, we create an instance of class Employee and check how it fetches the salary from DynamoDB.</p><p>I’m currently doing the same thing in almost every open source library I’m working with. I’m creating a collection of fake classes, that simplify testing inside the library and for its users.</p><p>BTW, a great article on the same subject: tl;dw: Stop mocking, start testing by Ned Batchelder.</p><p>PS. Check this out, on a very similar subject: Mocking of HTTP Server in Java.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>While mock objects are perfect instruments for unit testing, mocking through mock frameworks may turn your unit tests into an unmaintainable mess. Thanks to them we often hear that “mocking is bad” and “mocking is evil.”</p><p>The root cause of this complexity is that our objects are too big. They have many methods and these methods return other objects, which also have methods. When we pass a mock version of such an object as a parameter, we should make sure that all of its methods return valid objects.</p><p>This leads to inevitable complexity, which turns unit tests to waste almost impossible to maintain.</p><h2 id="object-hierarchy">Object Hierarchy</h2><p>Take the Region interface from jcabi-dynamo as an example (this snippet and all others in this article are simplified, for the sake of brevity):</p>
    <pre>public interface Region { Table table(String name); }</pre>
    <p>Its table() method returns an instance of the Table interface, which has its own methods:</p>
    <pre>public interface Table { Frame frame(); Item put(Attributes attrs); Region region(); }</pre>
    <p>Interface Frame, returned by the frame() method, also has its own methods. And so on. In order to create a properly mocked instance of interface Region, one would normally create a dozen other mock objects. With Mockito it will look like this:</p>
    <pre>public void testMe() { // many more lines here... Frame frame = Mockito.mock(Frame.class); Mockito.doReturn(...).when(frame).iterator(); Table table = Mockito.mock(Table.class); Mockito.doReturn(frame).when(table).frame(); Region region = Mockito.mock(Region.class); Mockito.doReturn(table).when(region).table(Mockito.anyString()); }</pre>
    <p>And all of this is just a scaffolding before the actual testing.</p><h2 id="sample-use-case">Sample Use Case</h2><p>Let’s say, you’re developing a project that uses jcabi-dynamo for managing data in DynamoDB. Your class may look similar to this:</p>
    <pre>public class Employee { private final String name; private final Region region; public Employee(String empl, Region dynamo) { this.name = empl; this.region = dynamo; } public Integer salary() { return Integer.parseInt( this.region .table("employees") .frame() .where("name", this.name) .iterator() .next() .get("salary") .getN() ); } }</pre>
    <p>You can imagine how difficult it will be to unit test this class, using Mockito, for example. First, we have to mock the Region interface. Then, we have to mock a Table interface and make sure it is returned by the table() method. Then, we have to mock a Frame interface, etc.</p><aside class="youtube"> <div class="box"> YouTube video #l6MpCBzwDbg<div class="play"></div></div><div>What Fake Objects Are For? (webinar #8); 4 November 2015.</div></aside><p>The unit test will be much longer than the class itself. Besides that, its real purpose, which is to test the retrieval of an employee’s salary, will not be obvious to the reader.</p><p>Moreover, when we need to test a similar method of a similar class, we will need to restart this mocking from scratch. Again, multiple lines of code, which will look very similar to what we have already written.</p><h2 id="fake-classes">Fake Classes</h2><p>The solution is to create fake classes and ship them together with real classes. This is what jcabi-dynamo is doing. Just look at its JavaDoc. There is a package called com.jcabi.dynamo.mock that contains only fake classes, suitable only for unit testing.</p><p>Even though their sole purpose is to optimize unit testing, we ship them together with production code, in the same JAR package.</p><p>This is what a test will look like, when a fake class MkRegion is used:</p>
    <pre>public class EmployeeTest { public void canFetchSalaryFromDynamoDb() { Region region = new MkRegion( new H2Data().with( "employees", new String[] {"name"}, new String[] {"salary"} ) ); region.table("employees").put( new Attributes() .with("name", "Jeff") .with("salary", new AttributeValue().withN(50000)) ); Employee emp = new Employee("Jeff", region); assertThat(emp.salary(), equalTo(50000)); } }</pre>
    <p>This test looks obvious to me. First, we create a fake DynamoDB region, which works on top of H2Data storage (in-memory H2 database). The storage will be ready for a single employees table with a hash key name and a single salary attribute.</p><aside class="youtube"> <div class="box"> YouTube video #EDKbYVEInMU<div class="play"></div></div><div>Built-in Fake Objects; 10 November 2016.</div></aside><p>Then, we put a record into the table, with a hash Jeff and a salary 50000.</p><p>Finally, we create an instance of class Employee and check how it fetches the salary from DynamoDB.</p><p>I’m currently doing the same thing in almost every open source library I’m working with. I’m creating a collection of fake classes, that simplify testing inside the library and for its users.</p><p>BTW, a great article on the same subject: tl;dw: Stop mocking, start testing by Ned Batchelder.</p><p>PS. Check this out, on a very similar subject: Mocking of HTTP Server in Java.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Getters/Setters. Evil. Period. </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/09/16/getters-and-setters-are-evil.html>12 Best</li> <li /2014/09/16/getters-and-setters-are-evil.html>All 292</li> <li /2014/09/16/getters-and-setters-are-evil.html>Webinars</li> <li /2014/09/16/getters-and-setters-are-evil.html>Talks</li> <li /2014/09/16/getters-and-setters-are-evil.html>Books</li> <li /2014/09/16/getters-and-setters-are-evil.html>Papers</li> <li /2014/09/16/getters-and-setters-are-evil.html>Pets</li> <li /2014/09/16/getters-and-setters-are-evil.html class=”highlighted”>Trainings</li> <li /2014/09/16/getters-and-setters-are-evil.html>Award</li> <li /2014/09/16/getters-and-setters-are-evil.html>Testimonials</li> <li /2014/09/16/getters-and-setters-are-evil.html>Shift-M</li> <li /2014/09/16/getters-and-setters-are-evil.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Getters/Setters. Evil. Period.</h1><aside class='book'>book coverRead more about this subject in Section 3.5
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Japanese</li> <li>Russian</li> <li>Polish</li> <li>add yours!</li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>There is an old debate, started in 2003 by Allen Holub in this Why getter and setter methods are evil famous article, about whether getters/setters is an anti-pattern and should be avoided or if it is something we inevitably need in object-oriented programming. I’ll try to add my two cents to this discussion.</p><p>The gist of the following text is this: getters and setters is a terrible practice and those who use it can’t be excused. Again, to avoid any misunderstanding, I’m not saying that get/set should be avoided when possible. No. I’m saying that you should never have them near your code.</p>
    A Fish Called Wanda (1988) by Charles Crichton<figcaption id="36b53fbe">A Fish Called Wanda (1988) by Charles Crichton</figcaption>
    <p>Arrogant enough to catch your attention? You’ve been using that get/set pattern for 15 years and you’re a respected Java architect? And you don’t want to hear that nonsense from a stranger? Well, I understand your feelings. I felt almost the same when I stumbled upon Object Thinking by David West, the best book about object-oriented programming I’ve read so far. So please. Calm down and try to understand while I try to explain.</p><h2 id="existing-arguments">Existing Arguments</h2>
    badge
    <p>There are a few arguments against “accessors” (another name for getters and setters), in an object-oriented world. All of them, I think, are not strong enough. Let’s briefly go through them.</p><p>Tell, Don’t Ask Allen Holub says, “Don’t ask for the information you need to do the work; ask the object that has the information to do the work for you.”</p><p>Violated Encapsulation Principle An object can be teared apart by other objects, since they are able to inject any new data into it, through setters. The object simply can’t encapsulate its own state safely enough, since anyone can alter it.</p><aside class="youtube"> <div class="box"> YouTube video #WSgP85kr6eU<div class="play"></div></div><div>Why Getters-and-Setters Is An Anti-Pattern? (webinar #4); 1 July 2015.</div></aside><p>Exposed Implementation Details If we can get an object out of another object, we are relying too much on the first object’s implementation details. If tomorrow it will change, say, the type of that result, we have to change our code as well.</p><p>All these justifications are reasonable, but they are missing the main point.</p><h2 id="fundamental-disbelief">Fundamental Disbelief</h2><p>Most programmers believe that an object is a data structure with methods. I’m quoting Getters and Setters Are Not Evil, an article by Bozhidar Bozhanov:</p><blockquote><p>But the majority of objects for which people generate getters and setters are simple data holders.</p></blockquote><p>This misconception is the consequence of a huge misunderstanding! Objects are not “simple data holders.” Objects are not data structures with attached methods. This “data holder” concept came to object-oriented programming from procedural languages, especially C and COBOL. I’ll say it again: an object is not a set of data elements and functions that manipulate them. An object is not a data entity.</p><p>What is it then?</p><h2 id="a-ball-and-a-dog">A Ball and A Dog</h2><p>In true object-oriented programming, objects are living creatures, like you and me. They are living organisms, with their own behavior, properties and a life cycle.</p><p>Can a living organism have a setter? Can you “set” a ball to a dog? Not really. But that is exactly what the following piece of software is doing:</p>
    <pre>Dog dog = new Dog(); dog.setBall(new Ball());</pre>
    <p>How does that sound?</p><p>Can you get a ball from a dog? Well, you probably can, if she ate it and you’re doing surgery. In that case, yes, we can “get” a ball from a dog. This is what I’m talking about:</p>
    <pre>Dog dog = new Dog(); Ball ball = dog.getBall();</pre>
    <p>Or an even more ridiculous example:</p>
    <pre>Dog dog = new Dog(); dog.setWeight("23kg");</pre>
    <p>Can you imagine this transaction in the real world? :)</p><aside class="youtube"> <div class="box"> YouTube video #F4N25kZ2zQU<div class="play"></div></div><div>Object Oriented Lies (in Russian with English subtitles); 24 April 2016.</div></aside><p>Does it look similar to what you’re writing every day? If yes, then you’re a procedural programmer. Admit it. And this is what David West has to say about it, on page 30 of his book:</p><blockquote><p>Step one in the transformation of a successful procedural developer into a successful object developer is a lobotomy.</p></blockquote><p>Do you need a lobotomy? Well, I definitely needed one and received it, while reading West’s Object Thinking.</p><h2 id="object-thinking">Object Thinking</h2><p>Start thinking like an object and you will immediately rename those methods. This is what you will probably get:</p>
    <pre>Dog dog = new Dog(); dog.take(new Ball()); Ball ball = dog.give();</pre>
    <p>Now, we’re treating the dog as a real animal, who can take a ball from us and can give it back, when we ask. Worth mentioning is that the dog can’t give NULL back. Dogs simply don’t know what NULL is :) Object thinking immediately eliminates NULL references from your code.</p><p>Besides that, object thinking will lead to object immutability, like in the “weight of the dog” example. You would re-write that like this instead:</p>
    <pre>Dog dog = new Dog("23kg"); int weight = dog.weight();</pre>
    <p>The dog is an immutable living organism, which doesn’t allow anyone from the outside to change her weight, or size, or name, etc. She can tell, on request, her weight or name. There is nothing wrong with public methods that demonstrate requests for certain “insides” of an object. But these methods are not “getters” and they should never have the “get” prefix. We’re not “getting” anything from the dog. We’re not getting her name. We’re asking her to tell us her name. See the difference?</p><p>We’re not talking semantics here, either. We are differentiating the procedural programming mindset from an object-oriented one. In procedural programming, we’re working with data, manipulating them, getting, setting, and deleting when necessary. We’re in charge, and the data is just a passive component. The dog is nothing to us—it’s just a “data holder.” It doesn’t have its own life. We are free to get whatever is necessary from it and set any data into it. This is how C, COBOL, Pascal and many other procedural languages work(ed).</p><p>On the contrary, in a true object-oriented world, we treat objects like living organisms, with their own date of birth and a moment of death—with their own identity and habits, if you wish. We can ask a dog to give us some piece of data (for example, her weight), and she may return us that information. But we always remember that the dog is an active component. She decides what will happen after our request.</p><p>That’s why, it is conceptually incorrect to have any methods starting with set or get in an object. And it’s not about breaking encapsulation, like many people argue. It is whether you’re thinking like an object or you’re still writing COBOL in Java syntax.</p><p>PS. Yes, you may ask,—what about JavaBeans, JPA, JAXB, and many other Java API-s that rely on the get/set notation? What about Ruby’s built-in feature that simplifies the creation of accessors? Well, all of that is our misfortune. It is much easier to stay in a primitive world of procedural COBOL than to truly understand and appreciate the beautiful world of true objects.</p><p>PPS. Forgot to say, yes, dependency injection via setters is also a terrible anti-pattern. About it, in one of the next posts :)</p><p>PPPS. Here is what I’m suggesting to use instead of getters: printers.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>There is an old debate, started in 2003 by Allen Holub in this Why getter and setter methods are evil famous article, about whether getters/setters is an anti-pattern and should be avoided or if it is something we inevitably need in object-oriented programming. I’ll try to add my two cents to this discussion.</p><p>The gist of the following text is this: getters and setters is a terrible practice and those who use it can’t be excused. Again, to avoid any misunderstanding, I’m not saying that get/set should be avoided when possible. No. I’m saying that you should never have them near your code.</p>
    A Fish Called Wanda (1988) by Charles Crichton<figcaption id="36b53fbe">A Fish Called Wanda (1988) by Charles Crichton</figcaption>
    <p>Arrogant enough to catch your attention? You’ve been using that get/set pattern for 15 years and you’re a respected Java architect? And you don’t want to hear that nonsense from a stranger? Well, I understand your feelings. I felt almost the same when I stumbled upon Object Thinking by David West, the best book about object-oriented programming I’ve read so far. So please. Calm down and try to understand while I try to explain.</p><h2 id="existing-arguments">Existing Arguments</h2>
    badge
    <p>There are a few arguments against “accessors” (another name for getters and setters), in an object-oriented world. All of them, I think, are not strong enough. Let’s briefly go through them.</p><p>Tell, Don’t Ask Allen Holub says, “Don’t ask for the information you need to do the work; ask the object that has the information to do the work for you.”</p><p>Violated Encapsulation Principle An object can be teared apart by other objects, since they are able to inject any new data into it, through setters. The object simply can’t encapsulate its own state safely enough, since anyone can alter it.</p><aside class="youtube"> <div class="box"> YouTube video #WSgP85kr6eU<div class="play"></div></div><div>Why Getters-and-Setters Is An Anti-Pattern? (webinar #4); 1 July 2015.</div></aside><p>Exposed Implementation Details If we can get an object out of another object, we are relying too much on the first object’s implementation details. If tomorrow it will change, say, the type of that result, we have to change our code as well.</p><p>All these justifications are reasonable, but they are missing the main point.</p><h2 id="fundamental-disbelief">Fundamental Disbelief</h2><p>Most programmers believe that an object is a data structure with methods. I’m quoting Getters and Setters Are Not Evil, an article by Bozhidar Bozhanov:</p><blockquote><p>But the majority of objects for which people generate getters and setters are simple data holders.</p></blockquote><p>This misconception is the consequence of a huge misunderstanding! Objects are not “simple data holders.” Objects are not data structures with attached methods. This “data holder” concept came to object-oriented programming from procedural languages, especially C and COBOL. I’ll say it again: an object is not a set of data elements and functions that manipulate them. An object is not a data entity.</p><p>What is it then?</p><h2 id="a-ball-and-a-dog">A Ball and A Dog</h2><p>In true object-oriented programming, objects are living creatures, like you and me. They are living organisms, with their own behavior, properties and a life cycle.</p><p>Can a living organism have a setter? Can you “set” a ball to a dog? Not really. But that is exactly what the following piece of software is doing:</p>
    <pre>Dog dog = new Dog(); dog.setBall(new Ball());</pre>
    <p>How does that sound?</p><p>Can you get a ball from a dog? Well, you probably can, if she ate it and you’re doing surgery. In that case, yes, we can “get” a ball from a dog. This is what I’m talking about:</p>
    <pre>Dog dog = new Dog(); Ball ball = dog.getBall();</pre>
    <p>Or an even more ridiculous example:</p>
    <pre>Dog dog = new Dog(); dog.setWeight("23kg");</pre>
    <p>Can you imagine this transaction in the real world? :)</p><aside class="youtube"> <div class="box"> YouTube video #F4N25kZ2zQU<div class="play"></div></div><div>Object Oriented Lies (in Russian with English subtitles); 24 April 2016.</div></aside><p>Does it look similar to what you’re writing every day? If yes, then you’re a procedural programmer. Admit it. And this is what David West has to say about it, on page 30 of his book:</p><blockquote><p>Step one in the transformation of a successful procedural developer into a successful object developer is a lobotomy.</p></blockquote><p>Do you need a lobotomy? Well, I definitely needed one and received it, while reading West’s Object Thinking.</p><h2 id="object-thinking">Object Thinking</h2><p>Start thinking like an object and you will immediately rename those methods. This is what you will probably get:</p>
    <pre>Dog dog = new Dog(); dog.take(new Ball()); Ball ball = dog.give();</pre>
    <p>Now, we’re treating the dog as a real animal, who can take a ball from us and can give it back, when we ask. Worth mentioning is that the dog can’t give NULL back. Dogs simply don’t know what NULL is :) Object thinking immediately eliminates NULL references from your code.</p><p>Besides that, object thinking will lead to object immutability, like in the “weight of the dog” example. You would re-write that like this instead:</p>
    <pre>Dog dog = new Dog("23kg"); int weight = dog.weight();</pre>
    <p>The dog is an immutable living organism, which doesn’t allow anyone from the outside to change her weight, or size, or name, etc. She can tell, on request, her weight or name. There is nothing wrong with public methods that demonstrate requests for certain “insides” of an object. But these methods are not “getters” and they should never have the “get” prefix. We’re not “getting” anything from the dog. We’re not getting her name. We’re asking her to tell us her name. See the difference?</p><p>We’re not talking semantics here, either. We are differentiating the procedural programming mindset from an object-oriented one. In procedural programming, we’re working with data, manipulating them, getting, setting, and deleting when necessary. We’re in charge, and the data is just a passive component. The dog is nothing to us—it’s just a “data holder.” It doesn’t have its own life. We are free to get whatever is necessary from it and set any data into it. This is how C, COBOL, Pascal and many other procedural languages work(ed).</p><p>On the contrary, in a true object-oriented world, we treat objects like living organisms, with their own date of birth and a moment of death—with their own identity and habits, if you wish. We can ask a dog to give us some piece of data (for example, her weight), and she may return us that information. But we always remember that the dog is an active component. She decides what will happen after our request.</p><p>That’s why, it is conceptually incorrect to have any methods starting with set or get in an object. And it’s not about breaking encapsulation, like many people argue. It is whether you’re thinking like an object or you’re still writing COBOL in Java syntax.</p><p>PS. Yes, you may ask,—what about JavaBeans, JPA, JAXB, and many other Java API-s that rely on the get/set notation? What about Ruby’s built-in feature that simplifies the creation of accessors? Well, all of that is our misfortune. It is much easier to stay in a primitive world of procedural COBOL than to truly understand and appreciate the beautiful world of true objects.</p><p>PPS. Forgot to say, yes, dependency injection via setters is also a terrible anti-pattern. About it, in one of the next posts :)</p><p>PPPS. Here is what I’m suggesting to use instead of getters: printers.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Deployment Script vs. Rultor </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/09/11/deployment-script-vs-rultor.html>12 Best</li> <li /2014/09/11/deployment-script-vs-rultor.html>All 292</li> <li /2014/09/11/deployment-script-vs-rultor.html>Webinars</li> <li /2014/09/11/deployment-script-vs-rultor.html>Talks</li> <li /2014/09/11/deployment-script-vs-rultor.html>Books</li> <li /2014/09/11/deployment-script-vs-rultor.html>Papers</li> <li /2014/09/11/deployment-script-vs-rultor.html>Pets</li> <li /2014/09/11/deployment-script-vs-rultor.html class=”highlighted”>Trainings</li> <li /2014/09/11/deployment-script-vs-rultor.html>Award</li> <li /2014/09/11/deployment-script-vs-rultor.html>Testimonials</li> <li /2014/09/11/deployment-script-vs-rultor.html>Shift-M</li> <li /2014/09/11/deployment-script-vs-rultor.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Deployment Script vs. Rultor</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
    badge
    <p>When I explain how Rultor automates deployment/release processes, very often I hear something like:</p><blockquote><p>But I already have a script that deploys everything automatically.</p></blockquote><p>This response is very common, so I decided to summarize my three main arguments for automated Rultor deployment/release processes in one article: 1) isolated docker containers, 2) visibility of logs and 3) security of credentials.</p><p>Read about them and see what Rultor gives you on top of your existing deployment script(s).</p>
    Charlie and the Chocolate Factory (2005) by Tim Burton<figcaption id="2ee88f79">Charlie and the Chocolate Factory (2005) by Tim Burton</figcaption>
    <p>Before we start with the arguments, let me emphasize that Rultor is a useful interface to your custom scripts. When you decide to automate deployment with Rultor, you don’t throw away any of your existing scripts. You just teach Rultor how to call them.</p><h2 id="isolated-docker-containers">Isolated Docker Containers</h2><aside class="youtube"> <div class="box"> YouTube video #NflR7DKwxDY<div class="play"></div></div><div>Deployment Scripts Are Dead. Meet Rultor.; 26 May 2016.</div></aside><p>The first advantage you get once you start calling your deployment scripts from Rultor is the usage of Docker. I’m sure you know what Docker is, but for those who don’t—it is a manager of virtual Linux “machines.” It’s a command line script that you call when you need to run some script in a new virtual machine (aka “container”). Docker starts the container almost immediately and runs your script. The beauty of Docker is that every container is a perfectly isolated Linux environment, with its own file system, memory, processes, etc.</p><p>When you tell Rultor to run your deployment script, it starts a new Docker container and runs your script there. But what benefit does this give me, you ask?</p><p>The main benefit is that the container gets destroyed right after your script is done. This means that you can do all pre-configuration inside the container without any fear of conflict with your main working platform. Let me give an example.</p><p>I’m developing on MacBook, where I install and remove packages which I need for development. At the same time, I have a project that, in order to be deployed, requires PHP 5.3, MySQL 5.6, Phing, PHPUnit, PHPCS and xdebug. Every MacOS version needs to be configured specifically to get these applications up and running, and it’s a time-consuming job.</p><p>I can change laptops, and I can change MacOS versions, but the project stays the same. It still requires the same set of packages in order to run its deployment script successfully. And the project is not in active development any more. I simply don’t need these packages for my day-to-day work, since I’m working with Java more now. But, when I need to make a minor fix to that PHP project and deploy it, I have to install all the required PHP packages and configure them. Only after that can I deploy that minor fix.</p><p>It is annoying, to say the least.</p><p>Docker gives me the ability to automate all of this together. My existing deployment script will get a preamble, which will install and configure all necessary PHP-related packages in a clean Ubuntu container. This preamble will be executed on every run of my deployment script, inside a Docker container. For example, it may look like this:</p><p>My deployment script looked like this before I started to use Rultor:</p>
    <pre>#!/bin/bash phing test git ftp push --user ".." \ --passwd ".." \ --syncroot php/src \ ftp://ftp.example.com/</pre>
    <p>Just two lines. The first one is a full run of unit tests. The second one is an FTP deployment to the production server. Very simple. But this script will only work if PHP 5.3, MySQL, Phing, xdebug, PHPCS and PHPUnit are installed. Again, it’s a lot of work to install and configure them every time I upgrade my MacOS or change a laptop.</p><aside class="youtube"> <div class="box"> YouTube video #_61CuGhyv-o<div class="play"></div></div><div>Practical Example of a One-Click Release; 15 November 2016.</div></aside><p>Needless to say, that if/when someone joins the project and tries to run my scripts, he/she will have to do this pre-installation work again.</p><p>So, here is a new script, which I’m using now. It is being executed inside a new Docker container, every time:</p>
    <pre>#!/bin/bash # First, we install all prerequisites sudo apt-get install -y php5 php5-mysql mysql sudo apt-get install php-pear sudo pear channel-discover pear.phpunit.de sudo pear install phpunit/PHPUnit sudo pear install PHP_CodeSniffer sudo pecl install xdebug sudo pear channel-discover pear.phing.info sudo pear install phing/phing # And now the same script I had before phing test git ftp push --user ".." \ --passwd ".." \ --syncroot php/src \ ftp://ftp.example.com/</pre>
    <p>Obviously, running this script on my MacBook (without virtualization) would cause a lot of trouble. Well, I don’t even have apt-get here :)</p><p>Thus, the first benefit that Rultor gives you is an isolation of your deployment script in its own virtual environment. We have this mostly thanks to Docker.</p><h2 id="visibility-of-logs">Visibility of Logs</h2><p>Traditionally, we keep deployment scripts in some ~/deploy directory and run them with a magic set of parameters. In a small project, you do this yourself and this directory is on your own laptop. In a bigger project, there is a “deployment” server, that has that magic directory with a set of scripts that can be executed only by a few trusted senior developers. I’ve seen this setup many times.</p><p>The biggest issue here is traceability. It’s almost impossible to find out who deployed what and why some particular deployment failed. The senior deployment gurus simply SSH to the server and run those magic scripts with magic parameters. Logs are usually lost and problem tracking is very difficult or impossible.</p><p>Rultor offers something different. With Rultor, there is no SSH access to deployment scripts any more. All scripts stay in the .rultor.yml configuration file, and you start them by posting messages in your issue tracking system (for example GitHub, JIRA or Trac). Rultor runs the script and publishes its full log right to your ticket. The log stays with your project forever. You can always get back to the ticket you were working with and check why deployment failed and what instructions were actually executed.</p><p>For example, check out this GitHub issue, where I was deploying a new version of Rultor itself, and failed a few times: yegor256/rultor#563. All my failed attempts are protocolled. I can always get back to them and investigate. For a big project this information is vital.</p><p>Thus, the second benefit of Rultor versus a standalone deployment script is visibility of every single operation.</p><h2 id="security-of-credentials">Security of Credentials</h2><p>When you have a custom script sitting in your laptop or in that secret team deployment server, your production credentials stay close to it. There is just no other way. If your software works with a database, it has to know login credentials (user name, password, DB name, port number, etc.). Well, in the worst case, some people just hard code that information right into the source code. We aren’t even going to discuss this case, that’s how bad it is.</p><p>But let’s say you separate your DB credentials from the source code. You will have something like a db.properties or db.ini file, which will be attached to the application right before deployment. You can also keep that file directly in the production server, which is even better, but not always possible, especially with PaaS deployments, for example.</p><p>A similar problem exists with deployments of artifacts to repositories. Say, you’re regularly deploying to RubyGems.org. Your ~/.gem/credentials will contain your secret API key.</p><p>So, very often, your deployment scripts are accompanied by some files with sensitive and secure information. And these files have this information in a plain, open format. No encryption, no protection. Just user names, passwords, codes and tokens in plain text.</p><p>Why is this bad? Well, for a single developer with a single laptop this doesn’t sound like a problem. Although, I don’t like the idea of losing a laptop somewhere in an airport with all credentials open and ready to be used. You may argue that there are disc protection tools, like FileVault for MacOS or BestCrypt for Windows. Yes, maybe.</p><p>But let’s see what happens when we have a team of developers, working together and sharing those deployment scripts and files with credentials. Once you give access to your deployment scripts to a new member of the team, you have to share all that sensitive data. There is just no way around it. In order to use the scripts he/she has to be able to open files with credentials.</p><p>This is a problem, if you care about the security of your data.</p><p>Rultor solves this problem by offering an on-the-fly GPG decryption of your sensitive data, right before they are used by your deployment scripts. In the .rultor.yml configuration file you just say:</p>
    <pre>decrypt: db.ini: "repo/db.ini.asc" deploy: script: ftp put db.ini production</pre>
    <p>Then, you encrypt your db.ini using a Rultor GPG key, and fearlessly commit db.ini.asc to the repository. Nobody will be able to open and read that file, except the Rultor server itself, right before running the deployment script.</p><p>Thus, the third benefit of Rultor versus a standalone deployment script is proper security of sensitive data.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
    badge
    <p>When I explain how Rultor automates deployment/release processes, very often I hear something like:</p><blockquote><p>But I already have a script that deploys everything automatically.</p></blockquote><p>This response is very common, so I decided to summarize my three main arguments for automated Rultor deployment/release processes in one article: 1) isolated docker containers, 2) visibility of logs and 3) security of credentials.</p><p>Read about them and see what Rultor gives you on top of your existing deployment script(s).</p>
    Charlie and the Chocolate Factory (2005) by Tim Burton<figcaption id="2ee88f79">Charlie and the Chocolate Factory (2005) by Tim Burton</figcaption>
    <p>Before we start with the arguments, let me emphasize that Rultor is a useful interface to your custom scripts. When you decide to automate deployment with Rultor, you don’t throw away any of your existing scripts. You just teach Rultor how to call them.</p><h2 id="isolated-docker-containers">Isolated Docker Containers</h2><aside class="youtube"> <div class="box"> YouTube video #NflR7DKwxDY<div class="play"></div></div><div>Deployment Scripts Are Dead. Meet Rultor.; 26 May 2016.</div></aside><p>The first advantage you get once you start calling your deployment scripts from Rultor is the usage of Docker. I’m sure you know what Docker is, but for those who don’t—it is a manager of virtual Linux “machines.” It’s a command line script that you call when you need to run some script in a new virtual machine (aka “container”). Docker starts the container almost immediately and runs your script. The beauty of Docker is that every container is a perfectly isolated Linux environment, with its own file system, memory, processes, etc.</p><p>When you tell Rultor to run your deployment script, it starts a new Docker container and runs your script there. But what benefit does this give me, you ask?</p><p>The main benefit is that the container gets destroyed right after your script is done. This means that you can do all pre-configuration inside the container without any fear of conflict with your main working platform. Let me give an example.</p><p>I’m developing on MacBook, where I install and remove packages which I need for development. At the same time, I have a project that, in order to be deployed, requires PHP 5.3, MySQL 5.6, Phing, PHPUnit, PHPCS and xdebug. Every MacOS version needs to be configured specifically to get these applications up and running, and it’s a time-consuming job.</p><p>I can change laptops, and I can change MacOS versions, but the project stays the same. It still requires the same set of packages in order to run its deployment script successfully. And the project is not in active development any more. I simply don’t need these packages for my day-to-day work, since I’m working with Java more now. But, when I need to make a minor fix to that PHP project and deploy it, I have to install all the required PHP packages and configure them. Only after that can I deploy that minor fix.</p><p>It is annoying, to say the least.</p><p>Docker gives me the ability to automate all of this together. My existing deployment script will get a preamble, which will install and configure all necessary PHP-related packages in a clean Ubuntu container. This preamble will be executed on every run of my deployment script, inside a Docker container. For example, it may look like this:</p><p>My deployment script looked like this before I started to use Rultor:</p>
    <pre>#!/bin/bash phing test git ftp push --user ".." \ --passwd ".." \ --syncroot php/src \ ftp://ftp.example.com/</pre>
    <p>Just two lines. The first one is a full run of unit tests. The second one is an FTP deployment to the production server. Very simple. But this script will only work if PHP 5.3, MySQL, Phing, xdebug, PHPCS and PHPUnit are installed. Again, it’s a lot of work to install and configure them every time I upgrade my MacOS or change a laptop.</p><aside class="youtube"> <div class="box"> YouTube video #_61CuGhyv-o<div class="play"></div></div><div>Practical Example of a One-Click Release; 15 November 2016.</div></aside><p>Needless to say, that if/when someone joins the project and tries to run my scripts, he/she will have to do this pre-installation work again.</p><p>So, here is a new script, which I’m using now. It is being executed inside a new Docker container, every time:</p>
    <pre>#!/bin/bash # First, we install all prerequisites sudo apt-get install -y php5 php5-mysql mysql sudo apt-get install php-pear sudo pear channel-discover pear.phpunit.de sudo pear install phpunit/PHPUnit sudo pear install PHP_CodeSniffer sudo pecl install xdebug sudo pear channel-discover pear.phing.info sudo pear install phing/phing # And now the same script I had before phing test git ftp push --user ".." \ --passwd ".." \ --syncroot php/src \ ftp://ftp.example.com/</pre>
    <p>Obviously, running this script on my MacBook (without virtualization) would cause a lot of trouble. Well, I don’t even have apt-get here :)</p><p>Thus, the first benefit that Rultor gives you is an isolation of your deployment script in its own virtual environment. We have this mostly thanks to Docker.</p><h2 id="visibility-of-logs">Visibility of Logs</h2><p>Traditionally, we keep deployment scripts in some ~/deploy directory and run them with a magic set of parameters. In a small project, you do this yourself and this directory is on your own laptop. In a bigger project, there is a “deployment” server, that has that magic directory with a set of scripts that can be executed only by a few trusted senior developers. I’ve seen this setup many times.</p><p>The biggest issue here is traceability. It’s almost impossible to find out who deployed what and why some particular deployment failed. The senior deployment gurus simply SSH to the server and run those magic scripts with magic parameters. Logs are usually lost and problem tracking is very difficult or impossible.</p><p>Rultor offers something different. With Rultor, there is no SSH access to deployment scripts any more. All scripts stay in the .rultor.yml configuration file, and you start them by posting messages in your issue tracking system (for example GitHub, JIRA or Trac). Rultor runs the script and publishes its full log right to your ticket. The log stays with your project forever. You can always get back to the ticket you were working with and check why deployment failed and what instructions were actually executed.</p><p>For example, check out this GitHub issue, where I was deploying a new version of Rultor itself, and failed a few times: yegor256/rultor#563. All my failed attempts are protocolled. I can always get back to them and investigate. For a big project this information is vital.</p><p>Thus, the second benefit of Rultor versus a standalone deployment script is visibility of every single operation.</p><h2 id="security-of-credentials">Security of Credentials</h2><p>When you have a custom script sitting in your laptop or in that secret team deployment server, your production credentials stay close to it. There is just no other way. If your software works with a database, it has to know login credentials (user name, password, DB name, port number, etc.). Well, in the worst case, some people just hard code that information right into the source code. We aren’t even going to discuss this case, that’s how bad it is.</p><p>But let’s say you separate your DB credentials from the source code. You will have something like a db.properties or db.ini file, which will be attached to the application right before deployment. You can also keep that file directly in the production server, which is even better, but not always possible, especially with PaaS deployments, for example.</p><p>A similar problem exists with deployments of artifacts to repositories. Say, you’re regularly deploying to RubyGems.org. Your ~/.gem/credentials will contain your secret API key.</p><p>So, very often, your deployment scripts are accompanied by some files with sensitive and secure information. And these files have this information in a plain, open format. No encryption, no protection. Just user names, passwords, codes and tokens in plain text.</p><p>Why is this bad? Well, for a single developer with a single laptop this doesn’t sound like a problem. Although, I don’t like the idea of losing a laptop somewhere in an airport with all credentials open and ready to be used. You may argue that there are disc protection tools, like FileVault for MacOS or BestCrypt for Windows. Yes, maybe.</p><p>But let’s see what happens when we have a team of developers, working together and sharing those deployment scripts and files with credentials. Once you give access to your deployment scripts to a new member of the team, you have to share all that sensitive data. There is just no way around it. In order to use the scripts he/she has to be able to open files with credentials.</p><p>This is a problem, if you care about the security of your data.</p><p>Rultor solves this problem by offering an on-the-fly GPG decryption of your sensitive data, right before they are used by your deployment scripts. In the .rultor.yml configuration file you just say:</p>
    <pre>decrypt: db.ini: "repo/db.ini.asc" deploy: script: ftp put db.ini production</pre>
    <p>Then, you encrypt your db.ini using a Rultor GPG key, and fearlessly commit db.ini.asc to the repository. Nobody will be able to open and read that file, except the Rultor server itself, right before running the deployment script.</p><p>Thus, the third benefit of Rultor versus a standalone deployment script is proper security of sensitive data.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> RESTful API and a Web Site in the Same URL </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/09/09/restful-web-sites.html>12 Best</li> <li /2014/09/09/restful-web-sites.html>All 292</li> <li /2014/09/09/restful-web-sites.html>Webinars</li> <li /2014/09/09/restful-web-sites.html>Talks</li> <li /2014/09/09/restful-web-sites.html>Books</li> <li /2014/09/09/restful-web-sites.html>Papers</li> <li /2014/09/09/restful-web-sites.html>Pets</li> <li /2014/09/09/restful-web-sites.html class=”highlighted”>Trainings</li> <li /2014/09/09/restful-web-sites.html>Award</li> <li /2014/09/09/restful-web-sites.html>Testimonials</li> <li /2014/09/09/restful-web-sites.html>Shift-M</li> <li /2014/09/09/restful-web-sites.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">RESTful API and a Web Site in the Same URL</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Look at GitHub RESTful API, for example. To get information about a repository you should make a GET request to api.github.com/repos/yegor256/rultor. In response, you will get a JSON document with all the details of the yegor256/rultor repository. Try it, the URL doesn’t require any authentication.</p><p>To open the same repository in a nice HTML+CSS page, you should use a different URL: github.com/yegor256/rultor. The URL is different, the server-side is definitely different, but the nature of the data is exactly the same. The only thing that changes is a representation layer.</p><p>In the first case, we get JSON; in the second—HTML.</p><p>How about combining them? How about using the same URL and the same server-side processing mechanism for both of them? How about shifting the whole rendering task to the client-side (the browser) and letting the server work solely with the data?</p>
    The Good, the Bad, The Wierd (2008) by Kim Jee-woon<figcaption id="a51703b7">The Good, the Bad, The Wierd (2008) by Kim Jee-woon</figcaption>
    <p>XSLT is the technology that can help us do this. In XML+XSLT in a Browser I explained briefly how it works in a browser. In a nutshell, the server returns an XML with some data and a link to the XSL stylesheet. The stylesheet, being executed in a browser, converts XML to HTML. XSL language is as powerful as any other rendering engine, like JSP, JSF, Tiles, or what have you. Actually, it is much more powerful.</p><p>Using this approach we literally remove the entire rendering layer (“View” in the MVC paradigm) from the server and move it to the browser.</p><p>If we can make it possible, the web server will expose just a RESTful API, and every response page will have an XSL stylesheet attached. What do we gain? We’ll discuss later, at the end of the post. Now, let’s see what problems we will face:</p><ol> <li><p>JSON doesn’t have a rendering layer. There is no such thing as XSLT for JSON. So, we will have to forget about JSON and stay with XML only. For me, this sounds perfectly all right. Others don’t like XML and prefer to work with JSON only. Never understood them :)</p></li> <li><p>XSLT 2.0 is not supported by all browsers. Even XSLT 1.0 is only supported by some of them. For example, Internet Explorer 8 doesn’t support XSLT at all.</p></li> <li><p>Browsers support only GET and POST HTTP methods, while traditional RESTful API-s exploit also, at least, PUT and DELETE.</p></li> </ol><p>The first problem is not really a problem. It’s just a matter of taste (and level of education). The last two problems are much more serious. Let’s discuss them.</p><h2 id="xsl-transformation-on-the-server">XSL Transformation on the Server</h2><p>XSLT is not supported by some browsers. How do we solve this?</p><p>I think that the best approach is to parse the User-Agent HTTP header in every request and make a guess, whether this particular version of the browser supports XSLT or not. It’s not so difficult to do, since this compatibility information is public.</p><p>If the browser doesn’t support XSLT, we can do the transformation on the server side. We already have the XML with data, generated by the server, and we already have the XSL attached to it. All we need to do is to apply the latter to the former and obtain an HTML page. Then, we return the HTML to the browser.</p><p>Besides that, we can also pay attention to the Accept header. If it is set to application/xml or text/xml, we return XML, no matter what User-Agent is saying. This means, basically, that some API client is talking to us, not a browser. And this client is not interested in HTML, but in pure data in XML format.</p><h2 id="post-instead-of-put">POST Instead of PUT</h2><p>There is no workaround for this. Browsers don’t know anything about PUT or DELETE. So, we should also forget them in our RESTful API-s. We should design our API using only two methods: GET and POST. Is this even possible? Yes. Why not? It won’t look as fancy as with all six methods (some API-s also use OPTIONS and HEAD), but it will work.</p><h2 id="what-do-we-gain">What Do We Gain?</h2><p>OK, here is the question—why do we need this? What’s wrong with the way most people work now? Why can’t we make a web site separate from the API? What benefits do we get if we combine them?</p><p>I’ve been combining them in all web applications I’ve worked with since 2011. And the biggest advantage I’m experiencing is avoiding code duplication.</p><p>It is obvious that in the server we don’t duplicate controllers (in the case of MVC). We have one layer of controllers, and they control both the API and the web site (since they are one thing now).</p><p>Avoiding code duplication is a very important achievement. Moreover, I believe that it is the most important target for any software project.</p><p>These small web apps work exactly as explained above: s3auth.com, stateful.co, bibrarian.com. They are all open source, and you can see their source code in GitHub.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Look at GitHub RESTful API, for example. To get information about a repository you should make a GET request to api.github.com/repos/yegor256/rultor. In response, you will get a JSON document with all the details of the yegor256/rultor repository. Try it, the URL doesn’t require any authentication.</p><p>To open the same repository in a nice HTML+CSS page, you should use a different URL: github.com/yegor256/rultor. The URL is different, the server-side is definitely different, but the nature of the data is exactly the same. The only thing that changes is a representation layer.</p><p>In the first case, we get JSON; in the second—HTML.</p><p>How about combining them? How about using the same URL and the same server-side processing mechanism for both of them? How about shifting the whole rendering task to the client-side (the browser) and letting the server work solely with the data?</p>
    The Good, the Bad, The Wierd (2008) by Kim Jee-woon<figcaption id="a51703b7">The Good, the Bad, The Wierd (2008) by Kim Jee-woon</figcaption>
    <p>XSLT is the technology that can help us do this. In XML+XSLT in a Browser I explained briefly how it works in a browser. In a nutshell, the server returns an XML with some data and a link to the XSL stylesheet. The stylesheet, being executed in a browser, converts XML to HTML. XSL language is as powerful as any other rendering engine, like JSP, JSF, Tiles, or what have you. Actually, it is much more powerful.</p><p>Using this approach we literally remove the entire rendering layer (“View” in the MVC paradigm) from the server and move it to the browser.</p><p>If we can make it possible, the web server will expose just a RESTful API, and every response page will have an XSL stylesheet attached. What do we gain? We’ll discuss later, at the end of the post. Now, let’s see what problems we will face:</p><ol> <li><p>JSON doesn’t have a rendering layer. There is no such thing as XSLT for JSON. So, we will have to forget about JSON and stay with XML only. For me, this sounds perfectly all right. Others don’t like XML and prefer to work with JSON only. Never understood them :)</p></li> <li><p>XSLT 2.0 is not supported by all browsers. Even XSLT 1.0 is only supported by some of them. For example, Internet Explorer 8 doesn’t support XSLT at all.</p></li> <li><p>Browsers support only GET and POST HTTP methods, while traditional RESTful API-s exploit also, at least, PUT and DELETE.</p></li> </ol><p>The first problem is not really a problem. It’s just a matter of taste (and level of education). The last two problems are much more serious. Let’s discuss them.</p><h2 id="xsl-transformation-on-the-server">XSL Transformation on the Server</h2><p>XSLT is not supported by some browsers. How do we solve this?</p><p>I think that the best approach is to parse the User-Agent HTTP header in every request and make a guess, whether this particular version of the browser supports XSLT or not. It’s not so difficult to do, since this compatibility information is public.</p><p>If the browser doesn’t support XSLT, we can do the transformation on the server side. We already have the XML with data, generated by the server, and we already have the XSL attached to it. All we need to do is to apply the latter to the former and obtain an HTML page. Then, we return the HTML to the browser.</p><p>Besides that, we can also pay attention to the Accept header. If it is set to application/xml or text/xml, we return XML, no matter what User-Agent is saying. This means, basically, that some API client is talking to us, not a browser. And this client is not interested in HTML, but in pure data in XML format.</p><h2 id="post-instead-of-put">POST Instead of PUT</h2><p>There is no workaround for this. Browsers don’t know anything about PUT or DELETE. So, we should also forget them in our RESTful API-s. We should design our API using only two methods: GET and POST. Is this even possible? Yes. Why not? It won’t look as fancy as with all six methods (some API-s also use OPTIONS and HEAD), but it will work.</p><h2 id="what-do-we-gain">What Do We Gain?</h2><p>OK, here is the question—why do we need this? What’s wrong with the way most people work now? Why can’t we make a web site separate from the API? What benefits do we get if we combine them?</p><p>I’ve been combining them in all web applications I’ve worked with since 2011. And the biggest advantage I’m experiencing is avoiding code duplication.</p><p>It is obvious that in the server we don’t duplicate controllers (in the case of MVC). We have one layer of controllers, and they control both the API and the web site (since they are one thing now).</p><p>Avoiding code duplication is a very important achievement. Moreover, I believe that it is the most important target for any software project.</p><p>These small web apps work exactly as explained above: s3auth.com, stateful.co, bibrarian.com. They are all open source, and you can see their source code in GitHub.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Simple Java SSH Client </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/09/02/java-ssh-client.html>12 Best</li> <li /2014/09/02/java-ssh-client.html>All 292</li> <li /2014/09/02/java-ssh-client.html>Webinars</li> <li /2014/09/02/java-ssh-client.html>Talks</li> <li /2014/09/02/java-ssh-client.html>Books</li> <li /2014/09/02/java-ssh-client.html>Papers</li> <li /2014/09/02/java-ssh-client.html>Pets</li> <li /2014/09/02/java-ssh-client.html class=”highlighted”>Trainings</li> <li /2014/09/02/java-ssh-client.html>Award</li> <li /2014/09/02/java-ssh-client.html>Testimonials</li> <li /2014/09/02/java-ssh-client.html>Shift-M</li> <li /2014/09/02/java-ssh-client.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Simple Java SSH Client</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>An execution of a shell command via SSH can be done in Java, in just a few lines, using jcabi-ssh:</p>
    <pre>String hello = new Shell.Plain( new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ) ).exec("echo 'Hello, world!'");</pre>
    <p>jcabi-ssh is a convenient wrapper of JSch, a well-known pure Java implementation of SSH2.</p><p>Here is a more complex scenario, where I upload a file via SSH and then read back its grepped content:</p>
    <pre>Shell shell = new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ); File file = new File("/tmp/data.txt"); new Shell.Safe(shell).exec( "cat > d.txt && grep 'some text' d.txt", new FileInputStream(file), Logger.stream(Level.INFO, this), Logger.stream(Level.WARNING, this) );</pre>
    <p>Class SSH, which implements interface Shell, has only one method, exec. This method accepts four arguments:</p>
    <pre>interface Shell { int exec( String cmd, InputStream stdin, OutputStream stdout, OutputStream stderr ); }</pre>
    <p>I think it’s obvious what these arguments are about.</p><p>There are also a few convenient decorators that make it easier to operate with simple commands.</p><h2 id="shellsafe">Shell.Safe</h2><p>Shell.Safe decorates an instance of Shell and throws an exception if the exec exit code is not equal to zero. This may be very useful when you want to make sure that your command executed successfully, but don’t want to duplicate if/throw in many places of your code.</p>
    <pre>Shell ssh = new Shell.Safe( new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ) );</pre>
    <h2 id="shellverbose">Shell.Verbose</h2><p>Shell.Verbose decorates an instance of Shell and copies stdout and stderr to the slf4j logging facility (using jcabi-log). Of course, you can combine decorators, for example:</p>
    <pre>Shell ssh = new Shell.Verbose( new Shell.Safe( new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ) ) );</pre>
    <h2 id="shellplain">Shell.Plain</h2><p>Shell.Plain is a wrapper of Shell that introduces a new exec method with only one argument, a command to execute. It also doesn’t return an exit code, but stdout instead. This should be very convenient when you want to execute a simple command and just get its output (I’m combining it with Shell.Safe for safety):</p>
    <pre>String login = new Shell.Plain(new Shell.Safe(ssh)).exec("whoami");</pre>
    <h2 id="download">Download</h2><p>You need a single dependency jcabi-ssh.jar in your Maven project (get its latest version in Maven Central):</p>
    <pre><dependency> <groupId>com.jcabi</groupId> <artifactId>jcabi-ssh</artifactId> </dependency></pre>
    <p>The project is in GitHub. If you have any problems, just submit an issue. I’ll try to help.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>An execution of a shell command via SSH can be done in Java, in just a few lines, using jcabi-ssh:</p>
    <pre>String hello = new Shell.Plain( new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ) ).exec("echo 'Hello, world!'");</pre>
    <p>jcabi-ssh is a convenient wrapper of JSch, a well-known pure Java implementation of SSH2.</p><p>Here is a more complex scenario, where I upload a file via SSH and then read back its grepped content:</p>
    <pre>Shell shell = new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ); File file = new File("/tmp/data.txt"); new Shell.Safe(shell).exec( "cat > d.txt && grep 'some text' d.txt", new FileInputStream(file), Logger.stream(Level.INFO, this), Logger.stream(Level.WARNING, this) );</pre>
    <p>Class SSH, which implements interface Shell, has only one method, exec. This method accepts four arguments:</p>
    <pre>interface Shell { int exec( String cmd, InputStream stdin, OutputStream stdout, OutputStream stderr ); }</pre>
    <p>I think it’s obvious what these arguments are about.</p><p>There are also a few convenient decorators that make it easier to operate with simple commands.</p><h2 id="shellsafe">Shell.Safe</h2><p>Shell.Safe decorates an instance of Shell and throws an exception if the exec exit code is not equal to zero. This may be very useful when you want to make sure that your command executed successfully, but don’t want to duplicate if/throw in many places of your code.</p>
    <pre>Shell ssh = new Shell.Safe( new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ) );</pre>
    <h2 id="shellverbose">Shell.Verbose</h2><p>Shell.Verbose decorates an instance of Shell and copies stdout and stderr to the slf4j logging facility (using jcabi-log). Of course, you can combine decorators, for example:</p>
    <pre>Shell ssh = new Shell.Verbose( new Shell.Safe( new SSH( "ssh.example.com", 22, "yegor", "-----BEGIN RSA PRIVATE KEY-----..." ) ) );</pre>
    <h2 id="shellplain">Shell.Plain</h2><p>Shell.Plain is a wrapper of Shell that introduces a new exec method with only one argument, a command to execute. It also doesn’t return an exit code, but stdout instead. This should be very convenient when you want to execute a simple command and just get its output (I’m combining it with Shell.Safe for safety):</p>
    <pre>String login = new Shell.Plain(new Shell.Safe(ssh)).exec("whoami");</pre>
    <h2 id="download">Download</h2><p>You need a single dependency jcabi-ssh.jar in your Maven project (get its latest version in Maven Central):</p>
    <pre><dependency> <groupId>com.jcabi</groupId> <artifactId>jcabi-ssh</artifactId> </dependency></pre>
    <p>The project is in GitHub. If you have any problems, just submit an issue. I’ll try to help.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> How to Release to Maven Central, in One Click </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/08/19/how-to-release-to-maven-central.html>12 Best</li> <li /2014/08/19/how-to-release-to-maven-central.html>All 292</li> <li /2014/08/19/how-to-release-to-maven-central.html>Webinars</li> <li /2014/08/19/how-to-release-to-maven-central.html>Talks</li> <li /2014/08/19/how-to-release-to-maven-central.html>Books</li> <li /2014/08/19/how-to-release-to-maven-central.html>Papers</li> <li /2014/08/19/how-to-release-to-maven-central.html>Pets</li> <li /2014/08/19/how-to-release-to-maven-central.html class=”highlighted”>Trainings</li> <li /2014/08/19/how-to-release-to-maven-central.html>Award</li> <li /2014/08/19/how-to-release-to-maven-central.html>Testimonials</li> <li /2014/08/19/how-to-release-to-maven-central.html>Shift-M</li> <li /2014/08/19/how-to-release-to-maven-central.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">How to Release to Maven Central, in One Click</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>When I release a new version of jcabi-aspects, a Java open source library, to Maven Central, it takes 30 seconds of my time. Maybe even less. Recently, I released version 0.17.2. You can see how it all happened, in GitHub issue #80:</p>
    The figure
    <p>As you see, I gave a command to Rultor, and it released a new version to Maven central. I didn’t do anything else.</p><p>Now let’s see how you can do the same. How you can configure your project so that the release of its new version to Maven Central takes just a few seconds of your time.</p><p>By the way, I assume that you’re hosting your project in GitHub. If not, this entire tutorial won’t work. If you are still not in GitHub, I would strongly recommend moving there.</p><h2 id="prepare-your-pom">Prepare Your POM</h2><aside class="youtube"> <div class="box"> YouTube video #rEK3Rk2lX3M<div class="play"></div></div><div>Cactoos 0.12 polishing and releasing (webinar #27); 2 August 2017.</div></aside><p>Make sure your pom.xml contains all elements required by Sonatype, explained in Central Sync Requirements. We will deploy to Sonatype, and they will synchronize all JAR (and not only) artifacts to Maven Central.</p><h2 id="register-a-project-with-sonatype">Register a Project With Sonatype</h2><p>Create an account in Sonatype JIRA and raise a ticket, asking to approve your groupId. This OSSRH Guide explains this step in more detail.</p><h2 id="create-and-distribute-a-gpg-key">Create and Distribute a GPG Key</h2><p>Create a GPG key and distribute it, as explained in this Working with PGP Signatures article.</p><p>When this step is done, you should have two files: pubring.gpg and secring.gpg.</p><h2 id="create-settingsxml">Create settings.xml</h2><p>Create settings.xml, next to the two .gpg files created in the previous step:</p>
    <pre><settings> <profiles> <profile> <id>foo</id> <!-- give it the name of your project --> <properties> <gpg.homedir>/home/r</gpg.homedir> <gpg.keyname>9A105525</gpg.keyname> <gpg.passphrase>my-secret</gpg.passphrase> </properties> </profile> </profiles> <servers> <server> <id>oss.sonatype.org</id> <username><!-- Sonatype JIRA user name --></username> <password><!-- Sonatype JIRA pwd --></password> </server> </servers> </settings></pre>
    <p>In this example, 9A105525 is the ID of your public key, and my-secret is the pass phrase you have used while generating the keys.</p><h2 id="encrypt-security-assets">Encrypt Security Assets</h2><p>Now, encrypt these three files with a rultor remote:</p>
    <pre>$ gem install rultor $ rultor encrypt -p me/test pubring.gpg $ rultor encrypt -p me/test secring.gpg $ rultor encrypt -p me/test settings.xml</pre>
    <p>Instead of me/test you should use the name of your GitHub project.</p><p>You will get three new files: pubring.gpg.asc, secring.gpg.asc and settings.xml.asc. Add them to the root directory of your project, commit and push. The files contain your secret information, but only the Rultor server can decrypt them.</p><h2 id="add-sonatype-repositories">Add Sonatype Repositories</h2><p>I would recommend using jcabi-parent, as a parent pom for your project. This will make many further steps unnecessary. If you’re using jcabi-parent, skip this step.</p><p>However, if you don’t use jcabi-parent, you should add these two repositories to your pom.xml:</p>
    <pre><project> [...] <distributionManagement> <repository> <id>oss.sonatype.org</id> <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url> </repository> <snapshotRepository> <id>oss.sonatype.org</id> <url>https://oss.sonatype.org/content/repositories/snapshots</url> </snapshotRepository> </distributionManagement> </project></pre>
    <h2 id="configure-gpg-plugin">Configure GPG Plugin</h2><p>Again, I’d recommend using jcabi-parent, which configures this plugin automatically. If you’re using it, skip this step.</p><p>Otherwise, add this plugin to your pom.xml:</p>
    <pre><project> [..] <build> [..] <plugins> [..] <plugin> <artifactId>maven-gpg-plugin</artifactId> <version>1.5</version> <executions> <execution> <id>sign-artifacts</id> <phase>verify</phase> <goals> <goal>sign</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <h2 id="configure-versions-plugin">Configure Versions Plugin</h2><p>Once again, I recommend using http://parent.jcabi.com. It configures all required plugins out-of-the-box. If you’re using it, skip this step.</p><p>Otherwise, add this plugin to your pom.xml:</p>
    <pre><project> [..] <build> [..] <plugins> [..] <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>versions-maven-plugin</artifactId> <version>2.1</version> <configuration> <generateBackupPoms>false</generateBackupPoms> </configuration> </plugin> </plugins> </build> </project></pre>
    <h2 id="configure-sonatype-plugin">Configure Sonatype Plugin</h2><p>Yes, you’re right, http://parent.jcabi.com will help you here as well. If you’re using it, skip this step too.</p><p>Otherwise, add these four plugins to your pom.xml:</p>
    <pre><project> [..] <build> [..] <plugins> [..] <plugin> <artifactId>maven-deploy-plugin</artifactId> <configuration> <skip>true</skip> </configuration> </plugin> <plugin> <artifactId>maven-source-plugin</artifactId> <executions> <execution> <id>package-sources</id> <goals> <goal>jar</goal> </goals> </execution> </executions> </plugin> <plugin> <artifactId>maven-javadoc-plugin</artifactId> <executions> <execution> <id>package-javadoc</id> <phase>package</phase> <goals> <goal>jar</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.sonatype.plugins</groupId> <artifactId>nexus-staging-maven-plugin</artifactId> <version>1.6</version> <extensions>true</extensions> <configuration> <serverId>oss.sonatype.org</serverId> <nexusUrl>https://oss.sonatype.org/</nexusUrl> <description>${project.version}</description> </configuration> <executions> <execution> <id>deploy-to-sonatype</id> <phase>deploy</phase> <goals> <goal>deploy</goal> <goal>release</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <h2 id="create-rultor-configuration">Create Rultor Configuration</h2><p>Create a .rultor.yml file in the root directory of your project (reference page explains this format in details):</p>
    <pre>decrypt: settings.xml: "repo/settings.xml.asc" pubring.gpg: "repo/pubring.gpg.asc" secring.gpg: "repo/secring.gpg.asc" release: script: | mvn versions:set "-DnewVersion=${tag}" git commit -am "${tag}" mvn clean deploy -Pjcabi --settings /home/r/settings.xml</pre>
    <p>You can compare your file with live Rultor configuration of jcabi-aspects.</p><h2 id="run-it">Run It!</h2>
    badge
    <p>Now it’s time to see how it all works. Create a new ticket in the GitHub issue tracker, and post something like that into it (read more about Rultor commands):</p>
    <pre>@rultor release, tag is `0.1`</pre>
    <p>You will get a response in a few seconds. The rest will be done by Rultor.</p><p>Enjoy :)</p><p>BTW, if something doesn’t work as I’ve explained, don’t hesitate to submit a ticket to Rultor issue tracker. I will try to help you.</p><p>Yeah, forgot to mention, Rultor is also doing two important things. First, it creates a GitHub release with a proper description. Second, it posts a tweet about the release, which you can retweet, to make an announcement to your followers. Both features are very convenient for me. For example:</p><blockquote class="twitter-tweet" lang="en"><p>DynamoDB Local Maven Plugin, 0.7.1 released https://t.co/C3KULouuKS</p>—rultor.com (@rultors) August 19, 2014</blockquote> </p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>When I release a new version of jcabi-aspects, a Java open source library, to Maven Central, it takes 30 seconds of my time. Maybe even less. Recently, I released version 0.17.2. You can see how it all happened, in GitHub issue #80:</p>
    The figure
    <p>As you see, I gave a command to Rultor, and it released a new version to Maven central. I didn’t do anything else.</p><p>Now let’s see how you can do the same. How you can configure your project so that the release of its new version to Maven Central takes just a few seconds of your time.</p><p>By the way, I assume that you’re hosting your project in GitHub. If not, this entire tutorial won’t work. If you are still not in GitHub, I would strongly recommend moving there.</p><h2 id="prepare-your-pom">Prepare Your POM</h2><aside class="youtube"> <div class="box"> YouTube video #rEK3Rk2lX3M<div class="play"></div></div><div>Cactoos 0.12 polishing and releasing (webinar #27); 2 August 2017.</div></aside><p>Make sure your pom.xml contains all elements required by Sonatype, explained in Central Sync Requirements. We will deploy to Sonatype, and they will synchronize all JAR (and not only) artifacts to Maven Central.</p><h2 id="register-a-project-with-sonatype">Register a Project With Sonatype</h2><p>Create an account in Sonatype JIRA and raise a ticket, asking to approve your groupId. This OSSRH Guide explains this step in more detail.</p><h2 id="create-and-distribute-a-gpg-key">Create and Distribute a GPG Key</h2><p>Create a GPG key and distribute it, as explained in this Working with PGP Signatures article.</p><p>When this step is done, you should have two files: pubring.gpg and secring.gpg.</p><h2 id="create-settingsxml">Create settings.xml</h2><p>Create settings.xml, next to the two .gpg files created in the previous step:</p>
    <pre><settings> <profiles> <profile> <id>foo</id> <!-- give it the name of your project --> <properties> <gpg.homedir>/home/r</gpg.homedir> <gpg.keyname>9A105525</gpg.keyname> <gpg.passphrase>my-secret</gpg.passphrase> </properties> </profile> </profiles> <servers> <server> <id>oss.sonatype.org</id> <username><!-- Sonatype JIRA user name --></username> <password><!-- Sonatype JIRA pwd --></password> </server> </servers> </settings></pre>
    <p>In this example, 9A105525 is the ID of your public key, and my-secret is the pass phrase you have used while generating the keys.</p><h2 id="encrypt-security-assets">Encrypt Security Assets</h2><p>Now, encrypt these three files with a rultor remote:</p>
    <pre>$ gem install rultor $ rultor encrypt -p me/test pubring.gpg $ rultor encrypt -p me/test secring.gpg $ rultor encrypt -p me/test settings.xml</pre>
    <p>Instead of me/test you should use the name of your GitHub project.</p><p>You will get three new files: pubring.gpg.asc, secring.gpg.asc and settings.xml.asc. Add them to the root directory of your project, commit and push. The files contain your secret information, but only the Rultor server can decrypt them.</p><h2 id="add-sonatype-repositories">Add Sonatype Repositories</h2><p>I would recommend using jcabi-parent, as a parent pom for your project. This will make many further steps unnecessary. If you’re using jcabi-parent, skip this step.</p><p>However, if you don’t use jcabi-parent, you should add these two repositories to your pom.xml:</p>
    <pre><project> [...] <distributionManagement> <repository> <id>oss.sonatype.org</id> <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url> </repository> <snapshotRepository> <id>oss.sonatype.org</id> <url>https://oss.sonatype.org/content/repositories/snapshots</url> </snapshotRepository> </distributionManagement> </project></pre>
    <h2 id="configure-gpg-plugin">Configure GPG Plugin</h2><p>Again, I’d recommend using jcabi-parent, which configures this plugin automatically. If you’re using it, skip this step.</p><p>Otherwise, add this plugin to your pom.xml:</p>
    <pre><project> [..] <build> [..] <plugins> [..] <plugin> <artifactId>maven-gpg-plugin</artifactId> <version>1.5</version> <executions> <execution> <id>sign-artifacts</id> <phase>verify</phase> <goals> <goal>sign</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <h2 id="configure-versions-plugin">Configure Versions Plugin</h2><p>Once again, I recommend using http://parent.jcabi.com. It configures all required plugins out-of-the-box. If you’re using it, skip this step.</p><p>Otherwise, add this plugin to your pom.xml:</p>
    <pre><project> [..] <build> [..] <plugins> [..] <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>versions-maven-plugin</artifactId> <version>2.1</version> <configuration> <generateBackupPoms>false</generateBackupPoms> </configuration> </plugin> </plugins> </build> </project></pre>
    <h2 id="configure-sonatype-plugin">Configure Sonatype Plugin</h2><p>Yes, you’re right, http://parent.jcabi.com will help you here as well. If you’re using it, skip this step too.</p><p>Otherwise, add these four plugins to your pom.xml:</p>
    <pre><project> [..] <build> [..] <plugins> [..] <plugin> <artifactId>maven-deploy-plugin</artifactId> <configuration> <skip>true</skip> </configuration> </plugin> <plugin> <artifactId>maven-source-plugin</artifactId> <executions> <execution> <id>package-sources</id> <goals> <goal>jar</goal> </goals> </execution> </executions> </plugin> <plugin> <artifactId>maven-javadoc-plugin</artifactId> <executions> <execution> <id>package-javadoc</id> <phase>package</phase> <goals> <goal>jar</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.sonatype.plugins</groupId> <artifactId>nexus-staging-maven-plugin</artifactId> <version>1.6</version> <extensions>true</extensions> <configuration> <serverId>oss.sonatype.org</serverId> <nexusUrl>https://oss.sonatype.org/</nexusUrl> <description>${project.version}</description> </configuration> <executions> <execution> <id>deploy-to-sonatype</id> <phase>deploy</phase> <goals> <goal>deploy</goal> <goal>release</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <h2 id="create-rultor-configuration">Create Rultor Configuration</h2><p>Create a .rultor.yml file in the root directory of your project (reference page explains this format in details):</p>
    <pre>decrypt: settings.xml: "repo/settings.xml.asc" pubring.gpg: "repo/pubring.gpg.asc" secring.gpg: "repo/secring.gpg.asc" release: script: | mvn versions:set "-DnewVersion=${tag}" git commit -am "${tag}" mvn clean deploy -Pjcabi --settings /home/r/settings.xml</pre>
    <p>You can compare your file with live Rultor configuration of jcabi-aspects.</p><h2 id="run-it">Run It!</h2>
    badge
    <p>Now it’s time to see how it all works. Create a new ticket in the GitHub issue tracker, and post something like that into it (read more about Rultor commands):</p>
    <pre>@rultor release, tag is `0.1`</pre>
    <p>You will get a response in a few seconds. The rest will be done by Rultor.</p><p>Enjoy :)</p><p>BTW, if something doesn’t work as I’ve explained, don’t hesitate to submit a ticket to Rultor issue tracker. I will try to help you.</p><p>Yeah, forgot to mention, Rultor is also doing two important things. First, it creates a GitHub release with a proper description. Second, it posts a tweet about the release, which you can retweet, to make an announcement to your followers. Both features are very convenient for me. For example:</p><blockquote class="twitter-tweet" lang="en"><p>DynamoDB Local Maven Plugin, 0.7.1 released https://t.co/C3KULouuKS</p>—rultor.com (@rultors) August 19, 2014</blockquote> </div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Objects Should Be Immutable </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/06/09/objects-should-be-immutable.html>12 Best</li> <li /2014/06/09/objects-should-be-immutable.html>All 292</li> <li /2014/06/09/objects-should-be-immutable.html>Webinars</li> <li /2014/06/09/objects-should-be-immutable.html>Talks</li> <li /2014/06/09/objects-should-be-immutable.html>Books</li> <li /2014/06/09/objects-should-be-immutable.html>Papers</li> <li /2014/06/09/objects-should-be-immutable.html>Pets</li> <li /2014/06/09/objects-should-be-immutable.html class=”highlighted”>Trainings</li> <li /2014/06/09/objects-should-be-immutable.html>Award</li> <li /2014/06/09/objects-should-be-immutable.html>Testimonials</li> <li /2014/06/09/objects-should-be-immutable.html>Shift-M</li> <li /2014/06/09/objects-should-be-immutable.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Objects Should Be Immutable</h1><aside class='book'>book coverRead more about this subject in Section 2.6
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="subline"> <li>Discussed at:</li> <li>reddit</li></ul><p class="unprintable"><p>In object-oriented programming, an object is immutable if its state can’t be modified after it is created. In Java, a good example of an immutable object is String. Once created, we can’t modify its state. We can request that it creates new strings, but its own state will never change.</p><p>However, there are not so many immutable classes in JDK. Take, for example, class Date. It is possible to modify its state using setTime().</p><aside class="youtube"> <div class="box"> YouTube video #KwP7Ay9Z-hc<div class="play"></div></div><div>Immutable Objects vs. Common Sense (webinar #2); 6 May 2015.</div></aside><p>I don’t know why the JDK designers decided to make these two very similar classes differently. However, I believe that the design of a mutable Date has many flaws, while the immutable String is much more in the spirit of the object-oriented paradigm.</p><p>Moreover, I think that all classes should be immutable in a perfect object-oriented world. Unfortunately, sometimes, it is technically not possible due to limitations in JVM. Nevertheless, we should always aim for the best.</p><p>This is an incomplete list of arguments in favor of immutability:</p><ul> <li>immutable objects are simpler to construct, test, and use</li> <li>truly immutable objects are always thread-safe</li> <li>they help to avoid temporal coupling</li> <li>their usage is side-effect free (no defensive copies)</li> <li>identity mutability problem is avoided</li> <li>they always have failure atomicity</li> <li>they are much easier to cache</li> <li>they prevent NULL references, which are bad</li></ul><p>Let’s discuss the most important arguments one by one.</p><h2 id="thread-safety">Thread Safety</h2><p>The first and the most obvious argument is that immutable objects are thread-safe. This means that multiple threads can access the same object at the same time, without clashing with another thread.</p>
    badge
    <p>If no object methods can modify its state, no matter how many of them and how often are being called parallel—they will work in their own memory space in stack.</p><p>Goetz et al. explained the advantages of immutable objects in more details in their very famous book Java Concurrency in Practice (highly recommended).</p><h2 id="avoiding-temporal-coupling">Avoiding Temporal Coupling</h2><p>Here is an example of temporal coupling (the code makes two consecutive HTTP POST requests, where the second one contains HTTP body):</p>
    <pre>Request request = new Request("http://localhost"); request.method("POST"); String first = request.fetch(); request.body("text=hello"); String second = request.fetch();</pre>
    <p>This code works. However, you must remember that the first request should be configured before the second one may happen. If we decide to remove the first request from the script, we will remove the second and the third line, and won’t get any errors from the compiler:</p>
    <pre>Request request = new Request("http://localhost"); // request.method("POST"); // String first = request.fetch(); request.body("text=hello"); String second = request.fetch();</pre>
    <p>Now, the script is broken although it compiled without errors. This is what temporal coupling is about—there is always some hidden information in the code that a programmer has to remember. In this example, we have to remember that the configuration for the first request is also used for the second one.</p><aside class="youtube"> <div class="box"> YouTube video #EnhRgXrHCC4<div class="play"></div></div><div>How Immutability Helps in OOP (in Russian with English subtitles); 21 May 2016.</div></aside><p>We have to remember that the second request should always stay together and be executed after the first one.</p><p>If Request class were immutable, the first snippet wouldn’t work in the first place, and would have been rewritten like:</p>
    <pre>final Request request = new Request(""); String first = request.method("POST").fetch(); String second = request.method("POST").body("text=hello").fetch();</pre>
    <p>Now, these two requests are not coupled. We can safely remove the first one, and the second one will still work correctly. You may point out that there is a code duplication. Yes, we should get rid of it and re-write the code:</p>
    <pre>final Request request = new Request(""); final Request post = request.method("POST"); String first = post.fetch(); String second = post.body("text=hello").fetch();</pre>
    <p>See, refactoring didn’t break anything and we still don’t have temporal coupling. The first request can be removed safely from the code without affecting the second one.</p><p>I hope this example demonstrates that the code manipulating immutable objects is more readable and maintainable, because it doesn’t have temporal coupling.</p><h2 id="avoiding-side-effects">Avoiding Side Effects</h2><p>Let’s try to use our Request class in a new method (now it is mutable):</p>
    <pre>public String post(Request request) { request.method("POST"); return request.fetch(); }</pre>
    <p>Let’s try to make two requests—the first with GET method and the second with POST:</p>
    <pre>Request request = new Request("http://localhost"); request.method("GET"); String first = this.post(request); String second = request.fetch();</pre>
    <p>Method post() has a “side effect”—it makes changes to the mutable object request. These changes are not really expected in this case. We expect it to make a POST request and return its body. We don’t want to read its documentation just to find out that behind the scene it also modifies the request we’re passing to it as an argument.</p><p>Needless to say, such side effects lead to bugs and maintainability issues. It would be much better to work with an immutable Request:</p>
    <pre>public String post(Request request) { return request.method("POST").fetch(); }</pre>
    <p>In this case, we may not have any side effects. Nobody can modify our request object, no matter where it is used and how deep through the call stack it is passed by method calls:</p>
    <pre>Request request = new Request("http://localhost").method("GET"); String first = this.post(request); String second = request.fetch();</pre>
    <p>This code is perfectly safe and side effect free.</p><h2 id="avoiding-identity-mutability">Avoiding Identity Mutability</h2><p>Very often, we want objects to be identical if their internal states are the same. Date class is a good example:</p>
    <pre>Date first = new Date(1L); Date second = new Date(1L); assert first.equals(second); // true</pre>
    <p>There are two different objects; however, they are equal to each other because their encapsulated states are the same. This is made possible through their custom overloaded implementation of equals() and hashCode() methods.</p><p>The consequence of this convenient approach being used with mutable objects is that every time we modify object’s state it changes its identity:</p>
    <pre>Date first = new Date(1L); Date second = new Date(1L); first.setTime(2L); assert first.equals(second); // false</pre>
    <p>This may look natural, until you start using your mutable objects as keys in maps:</p>
    <pre>Map<Date, String> map = new HashMap<>(); Date date = new Date(); map.put(date, "hello, world!"); date.setTime(12345L); assert map.containsKey(date); // false</pre>
    <p>When modifying the state of date object, we’re not expecting it to change its identity. We’re not expecting to lose an entry in the map just because the state of its key is changed. However, this is exactly what is happening in the example above.</p><aside class="youtube"> <div class="box"> YouTube video #p7m7_iiqaHI<div class="play"></div></div><div>How Much Immutability Is Enough?; 19 May 2016.</div></aside><p>When we add an object to the map, its hashCode() returns one value. This value is used by HashMap to place the entry into the internal hash table. When we call containsKey() hash code of the object is different (because it is based on its internal state) and HashMap can’t find it in the internal hash table.</p><p>It is a very annoying and difficult to debug side effects of mutable objects. Immutable objects avoid it completely.</p><h2 id="failure-atomicity">Failure Atomicity</h2><p>Here is a simple example:</p>
    <pre>public class Stack { private int size; private String[] items; public void push(String item) { size++; if (size > items.length) { throw new RuntimeException("stack overflow"); } items[size] = item; } }</pre>
    <p>It is obvious that an object of class Stack will be left in a broken state if it throws a runtime exception on overflow. Its size property will be incremented, while items won’t get a new element.</p>
    badge
    <p>Immutability prevents this problem. An object will never be left in a broken state because its state is modified only in its constructor. The constructor will either fail, rejecting object instantiation, or succeed, making a valid solid object, which never changes its encapsulated state.</p><p>For more on this subject, read Effective Java, 2nd Edition by Joshua Bloch.</p><h2 id="arguments-against-immutability">Arguments Against Immutability</h2><p>There are a number of arguments against immutability.</p><ol> <li><p>“Immutability is not for enterprise systems”. Very often, I hear people say that immutability is a fancy feature, while absolutely impractical in real enterprise systems. As a counter-argument, I can only show some examples of real-life applications that contain only immutable Java objects: jcabi-http, jcabi-xml, jcabi-github, jcabi-s3, jcabi-dynamo, jcabi-w3c, jcabi-jdbc, jcabi-simpledb, jcabi-ssh. The above are all Java libraries that work solely with immutable classes/objects. netbout.com and stateful.co are web applications that work solely with immutable objects.</p></li> <li><p>“It’s cheaper to update an existing object than create a new one”. Oracle thinks that “The impact of object creation is often overestimated and can be offset by some of the efficiency associated with immutable objects. These include decreased overhead due to garbage collection, and the elimination of code needed to protect mutable objects from corruption.” I agree.</p></li> </ol><p>If you have some other arguments, please post them below and I’ll try to comment.</p><p>P.S. Check takes.org, a Java web framework that consists entirely of immutable objects.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>In object-oriented programming, an object is immutable if its state can’t be modified after it is created. In Java, a good example of an immutable object is String. Once created, we can’t modify its state. We can request that it creates new strings, but its own state will never change.</p><p>However, there are not so many immutable classes in JDK. Take, for example, class Date. It is possible to modify its state using setTime().</p><aside class="youtube"> <div class="box"> YouTube video #KwP7Ay9Z-hc<div class="play"></div></div><div>Immutable Objects vs. Common Sense (webinar #2); 6 May 2015.</div></aside><p>I don’t know why the JDK designers decided to make these two very similar classes differently. However, I believe that the design of a mutable Date has many flaws, while the immutable String is much more in the spirit of the object-oriented paradigm.</p><p>Moreover, I think that all classes should be immutable in a perfect object-oriented world. Unfortunately, sometimes, it is technically not possible due to limitations in JVM. Nevertheless, we should always aim for the best.</p><p>This is an incomplete list of arguments in favor of immutability:</p><ul> <li>immutable objects are simpler to construct, test, and use</li> <li>truly immutable objects are always thread-safe</li> <li>they help to avoid temporal coupling</li> <li>their usage is side-effect free (no defensive copies)</li> <li>identity mutability problem is avoided</li> <li>they always have failure atomicity</li> <li>they are much easier to cache</li> <li>they prevent NULL references, which are bad</li></ul><p>Let’s discuss the most important arguments one by one.</p><h2 id="thread-safety">Thread Safety</h2><p>The first and the most obvious argument is that immutable objects are thread-safe. This means that multiple threads can access the same object at the same time, without clashing with another thread.</p>
    badge
    <p>If no object methods can modify its state, no matter how many of them and how often are being called parallel—they will work in their own memory space in stack.</p><p>Goetz et al. explained the advantages of immutable objects in more details in their very famous book Java Concurrency in Practice (highly recommended).</p><h2 id="avoiding-temporal-coupling">Avoiding Temporal Coupling</h2><p>Here is an example of temporal coupling (the code makes two consecutive HTTP POST requests, where the second one contains HTTP body):</p>
    <pre>Request request = new Request("http://localhost"); request.method("POST"); String first = request.fetch(); request.body("text=hello"); String second = request.fetch();</pre>
    <p>This code works. However, you must remember that the first request should be configured before the second one may happen. If we decide to remove the first request from the script, we will remove the second and the third line, and won’t get any errors from the compiler:</p>
    <pre>Request request = new Request("http://localhost"); // request.method("POST"); // String first = request.fetch(); request.body("text=hello"); String second = request.fetch();</pre>
    <p>Now, the script is broken although it compiled without errors. This is what temporal coupling is about—there is always some hidden information in the code that a programmer has to remember. In this example, we have to remember that the configuration for the first request is also used for the second one.</p><aside class="youtube"> <div class="box"> YouTube video #EnhRgXrHCC4<div class="play"></div></div><div>How Immutability Helps in OOP (in Russian with English subtitles); 21 May 2016.</div></aside><p>We have to remember that the second request should always stay together and be executed after the first one.</p><p>If Request class were immutable, the first snippet wouldn’t work in the first place, and would have been rewritten like:</p>
    <pre>final Request request = new Request(""); String first = request.method("POST").fetch(); String second = request.method("POST").body("text=hello").fetch();</pre>
    <p>Now, these two requests are not coupled. We can safely remove the first one, and the second one will still work correctly. You may point out that there is a code duplication. Yes, we should get rid of it and re-write the code:</p>
    <pre>final Request request = new Request(""); final Request post = request.method("POST"); String first = post.fetch(); String second = post.body("text=hello").fetch();</pre>
    <p>See, refactoring didn’t break anything and we still don’t have temporal coupling. The first request can be removed safely from the code without affecting the second one.</p><p>I hope this example demonstrates that the code manipulating immutable objects is more readable and maintainable, because it doesn’t have temporal coupling.</p><h2 id="avoiding-side-effects">Avoiding Side Effects</h2><p>Let’s try to use our Request class in a new method (now it is mutable):</p>
    <pre>public String post(Request request) { request.method("POST"); return request.fetch(); }</pre>
    <p>Let’s try to make two requests—the first with GET method and the second with POST:</p>
    <pre>Request request = new Request("http://localhost"); request.method("GET"); String first = this.post(request); String second = request.fetch();</pre>
    <p>Method post() has a “side effect”—it makes changes to the mutable object request. These changes are not really expected in this case. We expect it to make a POST request and return its body. We don’t want to read its documentation just to find out that behind the scene it also modifies the request we’re passing to it as an argument.</p><p>Needless to say, such side effects lead to bugs and maintainability issues. It would be much better to work with an immutable Request:</p>
    <pre>public String post(Request request) { return request.method("POST").fetch(); }</pre>
    <p>In this case, we may not have any side effects. Nobody can modify our request object, no matter where it is used and how deep through the call stack it is passed by method calls:</p>
    <pre>Request request = new Request("http://localhost").method("GET"); String first = this.post(request); String second = request.fetch();</pre>
    <p>This code is perfectly safe and side effect free.</p><h2 id="avoiding-identity-mutability">Avoiding Identity Mutability</h2><p>Very often, we want objects to be identical if their internal states are the same. Date class is a good example:</p>
    <pre>Date first = new Date(1L); Date second = new Date(1L); assert first.equals(second); // true</pre>
    <p>There are two different objects; however, they are equal to each other because their encapsulated states are the same. This is made possible through their custom overloaded implementation of equals() and hashCode() methods.</p><p>The consequence of this convenient approach being used with mutable objects is that every time we modify object’s state it changes its identity:</p>
    <pre>Date first = new Date(1L); Date second = new Date(1L); first.setTime(2L); assert first.equals(second); // false</pre>
    <p>This may look natural, until you start using your mutable objects as keys in maps:</p>
    <pre>Map<Date, String> map = new HashMap<>(); Date date = new Date(); map.put(date, "hello, world!"); date.setTime(12345L); assert map.containsKey(date); // false</pre>
    <p>When modifying the state of date object, we’re not expecting it to change its identity. We’re not expecting to lose an entry in the map just because the state of its key is changed. However, this is exactly what is happening in the example above.</p><aside class="youtube"> <div class="box"> YouTube video #p7m7_iiqaHI<div class="play"></div></div><div>How Much Immutability Is Enough?; 19 May 2016.</div></aside><p>When we add an object to the map, its hashCode() returns one value. This value is used by HashMap to place the entry into the internal hash table. When we call containsKey() hash code of the object is different (because it is based on its internal state) and HashMap can’t find it in the internal hash table.</p><p>It is a very annoying and difficult to debug side effects of mutable objects. Immutable objects avoid it completely.</p><h2 id="failure-atomicity">Failure Atomicity</h2><p>Here is a simple example:</p>
    <pre>public class Stack { private int size; private String[] items; public void push(String item) { size++; if (size > items.length) { throw new RuntimeException("stack overflow"); } items[size] = item; } }</pre>
    <p>It is obvious that an object of class Stack will be left in a broken state if it throws a runtime exception on overflow. Its size property will be incremented, while items won’t get a new element.</p>
    badge
    <p>Immutability prevents this problem. An object will never be left in a broken state because its state is modified only in its constructor. The constructor will either fail, rejecting object instantiation, or succeed, making a valid solid object, which never changes its encapsulated state.</p><p>For more on this subject, read Effective Java, 2nd Edition by Joshua Bloch.</p><h2 id="arguments-against-immutability">Arguments Against Immutability</h2><p>There are a number of arguments against immutability.</p><ol> <li><p>“Immutability is not for enterprise systems”. Very often, I hear people say that immutability is a fancy feature, while absolutely impractical in real enterprise systems. As a counter-argument, I can only show some examples of real-life applications that contain only immutable Java objects: jcabi-http, jcabi-xml, jcabi-github, jcabi-s3, jcabi-dynamo, jcabi-w3c, jcabi-jdbc, jcabi-simpledb, jcabi-ssh. The above are all Java libraries that work solely with immutable classes/objects. netbout.com and stateful.co are web applications that work solely with immutable objects.</p></li> <li><p>“It’s cheaper to update an existing object than create a new one”. Oracle thinks that “The impact of object creation is often overestimated and can be offset by some of the efficiency associated with immutable objects. These include decreased overhead due to garbage collection, and the elimination of code needed to protect mutable objects from corruption.” I agree.</p></li> </ol><p>If you have some other arguments, please post them below and I’ll try to comment.</p><p>P.S. Check takes.org, a Java web framework that consists entirely of immutable objects.</p></div></article></div><div class="wrapper"><div class="unprintable"> <hr/><p>If you like this article, you will definitely like these very relevant posts too:</p><p>Immutable Objects Are Not Dumb
    Immutable objects are not the same as passive data structures without setters, despite a very common mis-belief.</p><p>How an Immutable Object Can Have State and Behavior?
    Object state and behavior are two very different things, and confusing the two often leads to incorrect design.</p><p>Gradients of Immutability
    There are a few levels and forms of immutability in object-oriented programming, all of which can be used when they seem appropriate.</p></div></div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Java Method Logging with AOP and Annotations </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>12 Best</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>All 292</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Webinars</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Talks</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Books</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Papers</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Pets</li> <li /2014/06/01/aop-aspectj-java-method-logging.html class=”highlighted”>Trainings</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Award</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Testimonials</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Shift-M</li> <li /2014/06/01/aop-aspectj-java-method-logging.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Java Method Logging with AOP and Annotations</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable"><p>Sometimes, I want to log (through slf4j and log4j) every execution of a method, seeing what arguments it receives, what it returns and how much time every execution takes. This is how I’m doing it, with help of AspectJ, jcabi-aspects and Java 6 annotations:</p>
    <pre>public class Foo { @Loggable public int power(int x, int p) { return Math.pow(x, p); } }</pre>
    <p>This is what I see in log4j output:</p>
    <pre>[INFO] com.example.Foo #power(2, 10): 1024 in 12μs [INFO] com.example.Foo #power(3, 3): 27 in 4μs</pre>
    <p>Nice, isn’t it? Now, let’s see how it works.</p><h2 id="annotation-with-runtime-retention">Annotation with Runtime Retention</h2><p>Annotations is a technique introduced in Java 6. It is a meta-programming instrument that doesn’t change the way code works, but gives marks to certain elements (methods, classes or variables). In other words, annotations are just markers attached to the code that can be seen and read. Some annotations are designed to be seen at compile time only—they don’t exist in .class files after compilation. Others remain visible after compilation and can be accessed in runtime.</p><aside class="youtube"> <div class="box"> YouTube video #4SRoLYxvIQ8<div class="play"></div></div><div>Practical Example of AOP with AspectJ (in Russian with English subtitles); 28 October 2016.</div></aside><p>For example, @Override is of the first type (its retention type is SOURCE), while @Test from JUnit is of the second type (retention type is RUNTIME). @Loggable—the one I’m using in the script above—is an annotation of the second type, from jcabi-aspects. It stays with the byte-code in the .class file after compilation.</p><p>Again, it is important to understand that even though method power() is annotated and compiled, it doesn’t send anything to slf4j so far. It just contains a marker saying “please, log my execution.”</p><h2 id="aspect-oriented-programming-aop">Aspect Oriented Programming (AOP)</h2><p>AOP is a useful technique that enables adding executable blocks to the source code without explicitly changing it. In our example, we don’t want to log method execution inside the class. Instead, we want some other class to intercept every call to method power(), measure its execution time and send this information to slf4j.</p><p>We want that interceptor to understand our @Loggable annotation and log every call to that specific method power(). And, of course, the same interceptor should be used for other methods where we’ll place the same annotation in the future.</p><p>This case perfectly fits the original intent of AOP—to avoid re-implementation of some common behavior in multiple classes.</p><p>Logging is a supplementary feature to our main functionality, and we don’t want to pollute our code with multiple logging instructions. Instead, we want logging to happen behind the scenes.</p><p>In terms of AOP, our solution can be explained as creating an aspect that cross-cuts the code at certain join points and applies an around advice that implements the desired functionality.</p><h2 id="aspectj">AspectJ</h2><p>Let’s see what these magic words mean. But, first, let’s see how jcabi-aspects implements them using AspectJ (it’s a simplified example, full code you can find in MethodLogger.java):</p>
    <pre>@Aspect public class MethodLogger { @Around("execution(* *(..)) && @annotation(Loggable)") public Object around(ProceedingJoinPoint point) { long start = System.currentTimeMillis(); Object result = point.proceed(); Logger.info( "#%s(%s): %s in %[msec]s", MethodSignature.class.cast(point.getSignature()).getMethod().getName(), point.getArgs(), result, System.currentTimeMillis() - start ); return result; } }</pre>
    <p>This is an aspect with a single around advice around() inside. The aspect is annotated with @Aspect and advice is annotated with @Around. As discussed above, these annotations are just markers in .class files. They don’t do anything except provide some meta-information to those who are interested in runtime.</p><p>Annotation @Around has one parameter, which—in this case—says that the advice should be applied to a method if:</p><ol> <li><p>its visibility modifier is * (public, protected or private);</p></li> <li><p>its name is name * (any name);</p></li> <li><p>its arguments are .. (any arguments); and</p></li> <li><p>it is annotated with @Loggable</p></li> </ol><p>When a call to an annotated method is to be intercepted, method around() executes before executing the actual method. When a call to method power() is to be intercepted, method around() receives an instance of class ProceedingJoinPoint and must return an object, which will be used as a result of method power().</p><p>In order to call the original method, power(), the advice has to call proceed() of the join point object.</p><p>We compile this aspect and make it available in classpath together with our main file Foo.class. So far so good, but we need to take one last step in order to put our aspect into action—we should apply our advice.</p><h2 id="binary-aspect-weaving">Binary Aspect Weaving</h2><p>Aspect weaving is the name of the advice applying process. Aspect weaver modifies original code by injecting calls to aspects. AspectJ does exactly that. We give it two binary Java classes Foo.class and MethodLogger.class; it gives back three—modified Foo.class, Foo$AjcClosure1.class and unmodified MethodLogger.class.</p><aside class="quote">Without weaving, both classes and aspects are just compiled Java binaries with attached annotations</aside><p>In order to understand which advice should be applied to which methods, AspectJ weaver is using annotations from .class files. Also, it uses reflection to browse all classes on classpath. It analyzes which methods satisfy the conditions from the @Around annotation. Of course, it finds our method power().</p><p>So, there are two steps. First, we compile our .java files using javac and get two files. Then, AspectJ weaves/modifies them and creates its own extra class. Our Foo class looks something like this after weaving:</p>
    <pre>public class Foo { private final MethodLogger logger; @Loggable public int power(int x, int p) { return this.logger.around(point); } private int power_aroundBody(int x, int p) { return Math.pow(x, p); } }</pre>
    <p>AspectJ weaver moves our original functionality to a new method, power_aroundBody(), and redirects all power() calls to the aspect class MethodLogger.</p><p>Instead of one method power() in class Foo now we have four classes working together. From now on, this is what happens behind the scenes on every call to power():</p><p>PlantUML SVG diagram</p><p>Original functionality of method power() is indicated by the small green lifeline on the diagram.</p><p>As you see, the aspect weaving process connects together classes and aspects, transferring calls between them through join points. Without weaving, both classes and aspects are just compiled Java binaries with attached annotations.</p><h1 id="jcabi-aspects">jcabi-aspects</h1><p>jcabi-aspects is a JAR library that contains Loggable annotation and MethodLogger aspect (btw, there are many more aspects and annotations). You don’t need to write your own aspect for method logging. Just add a few dependencies to your classpath and configure jcabi-maven-plugin for aspect weaving (get their latest versions in Maven Central):</p>
    <pre><project> <dependencies> <dependency> <groupId>com.jcabi</groupId> <artifactId>jcabi-aspects</artifactId> </dependency> <dependency> <groupId>org.aspectj</groupId> <artifactId>aspectjrt</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>com.jcabi</groupId> <artifactId>jcabi-maven-plugin</artifactId> <executions> <execution> <goals> <goal>ajc</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <p>Since this weaving procedure takes a lot of configuration effort, I created a convenient Maven plugin with an ajc goal, which does the entire aspect weaving job. You can use AspectJ directly, but I recommend that you use jcabi-maven-plugin.</p><p>That’s it. Now you can use @com.jcabi.aspects.Loggable annotation and your methods will be logged through slf4j.</p><p>If something doesn’t work as explained, don’t hesitate to submit a GitHub issue.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>Sometimes, I want to log (through slf4j and log4j) every execution of a method, seeing what arguments it receives, what it returns and how much time every execution takes. This is how I’m doing it, with help of AspectJ, jcabi-aspects and Java 6 annotations:</p>
    <pre>public class Foo { @Loggable public int power(int x, int p) { return Math.pow(x, p); } }</pre>
    <p>This is what I see in log4j output:</p>
    <pre>[INFO] com.example.Foo #power(2, 10): 1024 in 12μs [INFO] com.example.Foo #power(3, 3): 27 in 4μs</pre>
    <p>Nice, isn’t it? Now, let’s see how it works.</p><h2 id="annotation-with-runtime-retention">Annotation with Runtime Retention</h2><p>Annotations is a technique introduced in Java 6. It is a meta-programming instrument that doesn’t change the way code works, but gives marks to certain elements (methods, classes or variables). In other words, annotations are just markers attached to the code that can be seen and read. Some annotations are designed to be seen at compile time only—they don’t exist in .class files after compilation. Others remain visible after compilation and can be accessed in runtime.</p><aside class="youtube"> <div class="box"> YouTube video #4SRoLYxvIQ8<div class="play"></div></div><div>Practical Example of AOP with AspectJ (in Russian with English subtitles); 28 October 2016.</div></aside><p>For example, @Override is of the first type (its retention type is SOURCE), while @Test from JUnit is of the second type (retention type is RUNTIME). @Loggable—the one I’m using in the script above—is an annotation of the second type, from jcabi-aspects. It stays with the byte-code in the .class file after compilation.</p><p>Again, it is important to understand that even though method power() is annotated and compiled, it doesn’t send anything to slf4j so far. It just contains a marker saying “please, log my execution.”</p><h2 id="aspect-oriented-programming-aop">Aspect Oriented Programming (AOP)</h2><p>AOP is a useful technique that enables adding executable blocks to the source code without explicitly changing it. In our example, we don’t want to log method execution inside the class. Instead, we want some other class to intercept every call to method power(), measure its execution time and send this information to slf4j.</p><p>We want that interceptor to understand our @Loggable annotation and log every call to that specific method power(). And, of course, the same interceptor should be used for other methods where we’ll place the same annotation in the future.</p><p>This case perfectly fits the original intent of AOP—to avoid re-implementation of some common behavior in multiple classes.</p><p>Logging is a supplementary feature to our main functionality, and we don’t want to pollute our code with multiple logging instructions. Instead, we want logging to happen behind the scenes.</p><p>In terms of AOP, our solution can be explained as creating an aspect that cross-cuts the code at certain join points and applies an around advice that implements the desired functionality.</p><h2 id="aspectj">AspectJ</h2><p>Let’s see what these magic words mean. But, first, let’s see how jcabi-aspects implements them using AspectJ (it’s a simplified example, full code you can find in MethodLogger.java):</p>
    <pre>@Aspect public class MethodLogger { @Around("execution(* *(..)) && @annotation(Loggable)") public Object around(ProceedingJoinPoint point) { long start = System.currentTimeMillis(); Object result = point.proceed(); Logger.info( "#%s(%s): %s in %[msec]s", MethodSignature.class.cast(point.getSignature()).getMethod().getName(), point.getArgs(), result, System.currentTimeMillis() - start ); return result; } }</pre>
    <p>This is an aspect with a single around advice around() inside. The aspect is annotated with @Aspect and advice is annotated with @Around. As discussed above, these annotations are just markers in .class files. They don’t do anything except provide some meta-information to those who are interested in runtime.</p><p>Annotation @Around has one parameter, which—in this case—says that the advice should be applied to a method if:</p><ol> <li><p>its visibility modifier is * (public, protected or private);</p></li> <li><p>its name is name * (any name);</p></li> <li><p>its arguments are .. (any arguments); and</p></li> <li><p>it is annotated with @Loggable</p></li> </ol><p>When a call to an annotated method is to be intercepted, method around() executes before executing the actual method. When a call to method power() is to be intercepted, method around() receives an instance of class ProceedingJoinPoint and must return an object, which will be used as a result of method power().</p><p>In order to call the original method, power(), the advice has to call proceed() of the join point object.</p><p>We compile this aspect and make it available in classpath together with our main file Foo.class. So far so good, but we need to take one last step in order to put our aspect into action—we should apply our advice.</p><h2 id="binary-aspect-weaving">Binary Aspect Weaving</h2><p>Aspect weaving is the name of the advice applying process. Aspect weaver modifies original code by injecting calls to aspects. AspectJ does exactly that. We give it two binary Java classes Foo.class and MethodLogger.class; it gives back three—modified Foo.class, Foo$AjcClosure1.class and unmodified MethodLogger.class.</p><aside class="quote">Without weaving, both classes and aspects are just compiled Java binaries with attached annotations</aside><p>In order to understand which advice should be applied to which methods, AspectJ weaver is using annotations from .class files. Also, it uses reflection to browse all classes on classpath. It analyzes which methods satisfy the conditions from the @Around annotation. Of course, it finds our method power().</p><p>So, there are two steps. First, we compile our .java files using javac and get two files. Then, AspectJ weaves/modifies them and creates its own extra class. Our Foo class looks something like this after weaving:</p>
    <pre>public class Foo { private final MethodLogger logger; @Loggable public int power(int x, int p) { return this.logger.around(point); } private int power_aroundBody(int x, int p) { return Math.pow(x, p); } }</pre>
    <p>AspectJ weaver moves our original functionality to a new method, power_aroundBody(), and redirects all power() calls to the aspect class MethodLogger.</p><p>Instead of one method power() in class Foo now we have four classes working together. From now on, this is what happens behind the scenes on every call to power():</p><p>PlantUML SVG diagram</p><p>Original functionality of method power() is indicated by the small green lifeline on the diagram.</p><p>As you see, the aspect weaving process connects together classes and aspects, transferring calls between them through join points. Without weaving, both classes and aspects are just compiled Java binaries with attached annotations.</p><h1 id="jcabi-aspects">jcabi-aspects</h1><p>jcabi-aspects is a JAR library that contains Loggable annotation and MethodLogger aspect (btw, there are many more aspects and annotations). You don’t need to write your own aspect for method logging. Just add a few dependencies to your classpath and configure jcabi-maven-plugin for aspect weaving (get their latest versions in Maven Central):</p>
    <pre><project> <dependencies> <dependency> <groupId>com.jcabi</groupId> <artifactId>jcabi-aspects</artifactId> </dependency> <dependency> <groupId>org.aspectj</groupId> <artifactId>aspectjrt</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>com.jcabi</groupId> <artifactId>jcabi-maven-plugin</artifactId> <executions> <execution> <goals> <goal>ajc</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project></pre>
    <p>Since this weaving procedure takes a lot of configuration effort, I created a convenient Maven plugin with an ajc goal, which does the entire aspect weaving job. You can use AspectJ directly, but I recommend that you use jcabi-maven-plugin.</p><p>That’s it. Now you can use @com.jcabi.aspects.Loggable annotation and your methods will be logged through slf4j.</p><p>If something doesn’t work as explained, don’t hesitate to submit a GitHub issue.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Why NULL is Bad? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/05/13/why-null-is-bad.html>12 Best</li> <li /2014/05/13/why-null-is-bad.html>All 292</li> <li /2014/05/13/why-null-is-bad.html>Webinars</li> <li /2014/05/13/why-null-is-bad.html>Talks</li> <li /2014/05/13/why-null-is-bad.html>Books</li> <li /2014/05/13/why-null-is-bad.html>Papers</li> <li /2014/05/13/why-null-is-bad.html>Pets</li> <li /2014/05/13/why-null-is-bad.html class=”highlighted”>Trainings</li> <li /2014/05/13/why-null-is-bad.html>Award</li> <li /2014/05/13/why-null-is-bad.html>Testimonials</li> <li /2014/05/13/why-null-is-bad.html>Shift-M</li> <li /2014/05/13/why-null-is-bad.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Why NULL is Bad?</h1><aside class='book'>book coverRead more about this subject in Section 2.6
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Japanese</li> <li>add yours!</li></ul><p class="unprintable"><p>A simple example of NULL usage in Java:</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); if (id == 0) { return null; } return new Employee(id); }</pre>
    <p>What is wrong with this method?</p><p>It may return NULL instead of an object—that’s what is wrong. NULL is a terrible practice in an object-oriented paradigm and should be avoided at all costs. There have been a number of opinions about this published already, including Null References, The Billion Dollar Mistake presentation by Tony Hoare and the entire Object Thinking book by David West.</p><p>Here, I’ll try to summarize all the arguments and show examples of how NULL usage can be avoided and replaced with proper object-oriented constructs.</p><p>Basically, there are two possible alternatives to NULL.</p><p>The first one is Null Object design pattern (the best way is to make it a constant):</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); if (id == 0) { return Employee.NOBODY; } return Employee(id); }</pre>
    <p>The second possible alternative is to fail fast by throwing an Exception when you can’t return an object:</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); if (id == 0) { throw new EmployeeNotFoundException(name); } return Employee(id); }</pre>
    <p>Now, let’s see the arguments against NULL.</p><p>Besides Tony Hoare’s presentation and David West’s book mentioned above, I read these publications before writing this post: Clean Code by Robert Martin, Code Complete by Steve McConnell, Say “No” to “Null” by John Sonmez, Is returning null bad design? discussion at StackOverflow.</p><h2 id="ad-hoc-error-handling">Ad-hoc Error Handling</h2><p>Every time you get an object as an input you must check whether it is NULL or a valid object reference. If you forget to check, a NullPointerException (NPE) may break execution in runtime. Thus, your logic becomes polluted with multiple checks and if/then/else forks:</p>
    <pre>// this is a terrible design, don't reuse Employee employee = dept.getByName("Jeffrey"); if (employee == null) { System.out.println("can't find an employee"); System.exit(-1); } else { employee.transferTo(dept2); }</pre>
    <p>This is how exceptional situations are supposed to be handled in C and other imperative procedural languages. OOP introduced exception handling primarily to get rid of these ad-hoc error handling blocks. In OOP, we let exceptions bubble up until they reach an application-wide error handler and our code becomes much cleaner and shorter:</p>
    <pre>dept.getByName("Jeffrey").transferTo(dept2);</pre>
    <p>Consider NULL references an inheritance of procedural programming, and use 1) Null Objects or 2) Exceptions instead.</p><h2 id="ambiguous-semantic">Ambiguous Semantic</h2><p>In order to explicitly convey its meaning, the function getByName() has to be named getByNameOrNullIfNotFound(). The same should happen with every function that returns an object or NULL. Otherwise, ambiguity is inevitable for a code reader. Thus, to keep semantic unambiguous, you should give longer names to functions.</p><p>To get rid of this ambiguity, always return a real object, a null object or throw an exception.</p><p>Some may argue that we sometimes have to return NULL, for the sake of performance. For example, method get() of interface Map in Java returns NULL when there is no such item in the map:</p>
    <pre>Employee employee = employees.get("Jeffrey"); if (employee == null) { throw new EmployeeNotFoundException(); } return employee;</pre>
    <p>This code searches the map only once due to the usage of NULL in Map. If we would refactor Map so that its method get() will throw an exception if nothing is found, our code will look like this:</p>
    <pre>if (!employees.containsKey("Jeffrey")) { // first search throw new EmployeeNotFoundException(); } return employees.get("Jeffrey"); // second search</pre>
    <p>Obviously, this is method is twice as slow as the first one. What to do?</p><p>The Map interface (no offense to its authors) has a design flaw. Its method get() should have been returning an Iterator so that our code would look like:</p>
    <pre>Iterator found = Map.search("Jeffrey"); if (!found.hasNext()) { throw new EmployeeNotFoundException(); } return found.next();</pre>
    <p>BTW, that is exactly how C++ STL map::find() method is designed.</p><h2 id="computer-thinking-vs-object-thinking">Computer Thinking vs. Object Thinking</h2><p>Statement if (employee == null) is understood by someone who knows that an object in Java is a pointer to a data structure and that NULL is a pointer to nothing (0x00000000, in Intel x86 processors).</p><p>However, if you start thinking as an object, this statement makes much less sense. This is how our code looks from an object point of view:</p>
    <pre>- Hello, is it a software department?
  • Yes.
  • Let me talk to your employee "Jeffrey" please.
  • Hold the line please…
  • Hello.
  • Are you NULL?</code></pre></figure><p>The last question in this conversation sounds weird, doesn’t it?</p><p>Instead, if they hang up the phone after our request to speak to Jeffrey, that causes a problem for us (Exception). At that point, we try to call again or inform our supervisor that we can’t reach Jeffrey and complete a bigger transaction.</p><p>Alternatively, they may let us speak to another person, who is not Jeffrey, but who can help with most of our questions or refuse to help if we need something “Jeffrey specific” (Null Object).</p><h2 id="slow-failing">Slow Failing</h2><p>Instead of failing fast, the code above attempts to die slowly, killing others on its way. Instead of letting everyone know that something went wrong and that an exception handling should start immediately, it is hiding this failure from its client.</p><p>This argument is close to the “ad-hoc error handling” discussed above.</p><p>It is a good practice to make your code as fragile as possible, letting it break when necessary.</p><aside class="youtube"> <div class="box"> YouTube video #o3aNJX7AP3M<div class="play"></div></div><div>What is Wrong About NULL in OOP? (webinar #3); 3 June 2015.</div></aside><p>Make your methods extremely demanding as to the data they manipulate. Let them complain by throwing exceptions, if the provided data provided is not sufficient or simply doesn’t fit with the main usage scenario of the method.</p><p>Otherwise, return a Null Object, that exposes some common behavior and throws exceptions on all other calls:</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); Employee employee; if (id == 0) { employee = new Employee() { @Override public String name() { return "anonymous"; } @Override public void transferTo(Department dept) { throw new AnonymousEmployeeException( "I can't be transferred, I'm anonymous" ); } }; } else { employee = Employee(id); } return employee; }</pre>
    <blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Say, you are designing a method findUserByName(), which has to find a user in the database. What would you return if nothing is found? #elegantobjects</p>— Yegor Bugayenko (@yegor256) April 29, 2018</blockquote> <h2 id="mutable-and-incomplete-objects">Mutable and Incomplete Objects</h2><p>In general, it is highly recommended to design objects with immutability in mind. This means that an object gets all necessary knowledge during its instantiating and never changes its state during the entire life-cycle.</p><p>Very often, NULL values are used in lazy loading, to make objects incomplete and mutable. For example:</p>
    <pre>public class Department { private Employee found = null; public synchronized Employee manager() { if (this.found == null) { this.found = new Employee("Jeffrey"); } return this.found; } }</pre>
    <p>This technology, although widely used, is an anti-pattern in OOP. Mostly because it makes an object responsible for performance problems of the computational platform, which is something an Employee object should not be aware of.</p><p>Instead of managing a state and exposing its business-relevant behavior, an object has to take care of the caching of its own results—this is what lazy loading is about.</p><p>Caching is not something an employee does in the office, does he?</p><p>The solution? Don’t use lazy loading in such a primitive way, as in the example above. Instead, move this caching problem to another layer of your application.</p><p>For example, in Java, you can use aspect-oriented programming aspects. For example, jcabi-aspects has @Cacheable annotation that caches the value returned by a method:</p>
    <pre>import com.jcabi.aspects.Cacheable; public class Department { @Cacheable(forever = true) public Employee manager() { return new Employee("Jacky Brown"); } }</pre>
    <p>I hope this analysis was convincing enough that you will stop NULL-ing your code :)</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>A simple example of NULL usage in Java:</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); if (id == 0) { return null; } return new Employee(id); }</pre>
    <p>What is wrong with this method?</p><p>It may return NULL instead of an object—that’s what is wrong. NULL is a terrible practice in an object-oriented paradigm and should be avoided at all costs. There have been a number of opinions about this published already, including Null References, The Billion Dollar Mistake presentation by Tony Hoare and the entire Object Thinking book by David West.</p><p>Here, I’ll try to summarize all the arguments and show examples of how NULL usage can be avoided and replaced with proper object-oriented constructs.</p><p>Basically, there are two possible alternatives to NULL.</p><p>The first one is Null Object design pattern (the best way is to make it a constant):</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); if (id == 0) { return Employee.NOBODY; } return Employee(id); }</pre>
    <p>The second possible alternative is to fail fast by throwing an Exception when you can’t return an object:</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); if (id == 0) { throw new EmployeeNotFoundException(name); } return Employee(id); }</pre>
    <p>Now, let’s see the arguments against NULL.</p><p>Besides Tony Hoare’s presentation and David West’s book mentioned above, I read these publications before writing this post: Clean Code by Robert Martin, Code Complete by Steve McConnell, Say “No” to “Null” by John Sonmez, Is returning null bad design? discussion at StackOverflow.</p><h2 id="ad-hoc-error-handling">Ad-hoc Error Handling</h2><p>Every time you get an object as an input you must check whether it is NULL or a valid object reference. If you forget to check, a NullPointerException (NPE) may break execution in runtime. Thus, your logic becomes polluted with multiple checks and if/then/else forks:</p>
    <pre>// this is a terrible design, don't reuse Employee employee = dept.getByName("Jeffrey"); if (employee == null) { System.out.println("can't find an employee"); System.exit(-1); } else { employee.transferTo(dept2); }</pre>
    <p>This is how exceptional situations are supposed to be handled in C and other imperative procedural languages. OOP introduced exception handling primarily to get rid of these ad-hoc error handling blocks. In OOP, we let exceptions bubble up until they reach an application-wide error handler and our code becomes much cleaner and shorter:</p>
    <pre>dept.getByName("Jeffrey").transferTo(dept2);</pre>
    <p>Consider NULL references an inheritance of procedural programming, and use 1) Null Objects or 2) Exceptions instead.</p><h2 id="ambiguous-semantic">Ambiguous Semantic</h2><p>In order to explicitly convey its meaning, the function getByName() has to be named getByNameOrNullIfNotFound(). The same should happen with every function that returns an object or NULL. Otherwise, ambiguity is inevitable for a code reader. Thus, to keep semantic unambiguous, you should give longer names to functions.</p><p>To get rid of this ambiguity, always return a real object, a null object or throw an exception.</p><p>Some may argue that we sometimes have to return NULL, for the sake of performance. For example, method get() of interface Map in Java returns NULL when there is no such item in the map:</p>
    <pre>Employee employee = employees.get("Jeffrey"); if (employee == null) { throw new EmployeeNotFoundException(); } return employee;</pre>
    <p>This code searches the map only once due to the usage of NULL in Map. If we would refactor Map so that its method get() will throw an exception if nothing is found, our code will look like this:</p>
    <pre>if (!employees.containsKey("Jeffrey")) { // first search throw new EmployeeNotFoundException(); } return employees.get("Jeffrey"); // second search</pre>
    <p>Obviously, this is method is twice as slow as the first one. What to do?</p><p>The Map interface (no offense to its authors) has a design flaw. Its method get() should have been returning an Iterator so that our code would look like:</p>
    <pre>Iterator found = Map.search("Jeffrey"); if (!found.hasNext()) { throw new EmployeeNotFoundException(); } return found.next();</pre>
    <p>BTW, that is exactly how C++ STL map::find() method is designed.</p><h2 id="computer-thinking-vs-object-thinking">Computer Thinking vs. Object Thinking</h2><p>Statement if (employee == null) is understood by someone who knows that an object in Java is a pointer to a data structure and that NULL is a pointer to nothing (0x00000000, in Intel x86 processors).</p><p>However, if you start thinking as an object, this statement makes much less sense. This is how our code looks from an object point of view:</p>
    <pre>- Hello, is it a software department?
  • Yes.
  • Let me talk to your employee "Jeffrey" please.
  • Hold the line please…
  • Hello.
  • Are you NULL?</code></pre></figure><p>The last question in this conversation sounds weird, doesn’t it?</p><p>Instead, if they hang up the phone after our request to speak to Jeffrey, that causes a problem for us (Exception). At that point, we try to call again or inform our supervisor that we can’t reach Jeffrey and complete a bigger transaction.</p><p>Alternatively, they may let us speak to another person, who is not Jeffrey, but who can help with most of our questions or refuse to help if we need something “Jeffrey specific” (Null Object).</p><h2 id="slow-failing">Slow Failing</h2><p>Instead of failing fast, the code above attempts to die slowly, killing others on its way. Instead of letting everyone know that something went wrong and that an exception handling should start immediately, it is hiding this failure from its client.</p><p>This argument is close to the “ad-hoc error handling” discussed above.</p><p>It is a good practice to make your code as fragile as possible, letting it break when necessary.</p><aside class="youtube"> <div class="box"> YouTube video #o3aNJX7AP3M<div class="play"></div></div><div>What is Wrong About NULL in OOP? (webinar #3); 3 June 2015.</div></aside><p>Make your methods extremely demanding as to the data they manipulate. Let them complain by throwing exceptions, if the provided data provided is not sufficient or simply doesn’t fit with the main usage scenario of the method.</p><p>Otherwise, return a Null Object, that exposes some common behavior and throws exceptions on all other calls:</p>
    <pre>public Employee getByName(String name) { int id = database.find(name); Employee employee; if (id == 0) { employee = new Employee() { @Override public String name() { return "anonymous"; } @Override public void transferTo(Department dept) { throw new AnonymousEmployeeException( "I can't be transferred, I'm anonymous" ); } }; } else { employee = Employee(id); } return employee; }</pre>
    <blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Say, you are designing a method findUserByName(), which has to find a user in the database. What would you return if nothing is found? #elegantobjects</p>— Yegor Bugayenko (@yegor256) April 29, 2018</blockquote> <h2 id="mutable-and-incomplete-objects">Mutable and Incomplete Objects</h2><p>In general, it is highly recommended to design objects with immutability in mind. This means that an object gets all necessary knowledge during its instantiating and never changes its state during the entire life-cycle.</p><p>Very often, NULL values are used in lazy loading, to make objects incomplete and mutable. For example:</p>
    <pre>public class Department { private Employee found = null; public synchronized Employee manager() { if (this.found == null) { this.found = new Employee("Jeffrey"); } return this.found; } }</pre>
    <p>This technology, although widely used, is an anti-pattern in OOP. Mostly because it makes an object responsible for performance problems of the computational platform, which is something an Employee object should not be aware of.</p><p>Instead of managing a state and exposing its business-relevant behavior, an object has to take care of the caching of its own results—this is what lazy loading is about.</p><p>Caching is not something an employee does in the office, does he?</p><p>The solution? Don’t use lazy loading in such a primitive way, as in the example above. Instead, move this caching problem to another layer of your application.</p><p>For example, in Java, you can use aspect-oriented programming aspects. For example, jcabi-aspects has @Cacheable annotation that caches the value returned by a method:</p>
    <pre>import com.jcabi.aspects.Cacheable; public class Department { @Cacheable(forever = true) public Employee manager() { return new Employee("Jacky Brown"); } }</pre>
    <p>I hope this analysis was convincing enough that you will stop NULL-ing your code :)</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> OOP Alternative to Utility Classes </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>12 Best</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>All 292</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Webinars</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Talks</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Books</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Papers</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Pets</li> <li /2014/05/05/oop-alternative-to-utility-classes.html class=”highlighted”>Trainings</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Award</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Testimonials</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Shift-M</li> <li /2014/05/05/oop-alternative-to-utility-classes.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">OOP Alternative to Utility Classes</h1><aside class='book'>book coverRead more about this subject in Section 3.2
    of my bookClick to buy</aside><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Japanese</li> <li>Russian</li> <li>add yours!</li></ul><p class="unprintable"><p>A utility class (aka helper class) is a “structure” that has only static methods and encapsulates no state. StringUtils, IOUtils, FileUtils from Apache Commons; Iterables and Iterators from Guava, and Files from JDK7 are perfect examples of utility classes.</p><p>This design idea is very popular in the Java world (as well as C#, Ruby, etc.) because utility classes provide common functionality used everywhere.</p><aside class="youtube"> <div class="box"> YouTube video #psrp3TtaYYI<div class="play"></div></div><div>What’s Wrong About Utility Classes? (webinar #6); 2 September 2015.</div></aside><p>Here, we want to follow the DRY principle and avoid duplication. Therefore, we place common code blocks into utility classes and reuse them when necessary:</p>
    <pre>// This is a terrible design, don't reuse public class NumberUtils { public static int max(int a, int b) { return a > b ? a : b; } }</pre>
    <p>Indeed, this a very convenient technique!?</p><h2 id="utility-classes-are-evil">Utility Classes Are Evil</h2><p>However, in an object-oriented world, utility classes are considered a very bad (some even may say “terrible”) practice.</p><p>There have been many discussions of this subject; to name a few: Are Helper Classes Evil? by Nick Malik, Why helper, singletons and utility classes are mostly bad by Simon Hart, Avoiding Utility Classes by Marshal Ward, Kill That Util Class! by Dhaval Dalal, Helper Classes Are A Code Smell by Rob Bagby.</p><p>Additionally, there are a few questions on StackExchange about utility classes: If a “Utilities” class is evil, where do I put my generic code?, Utility Classes are Evil.</p><p>A dry summary of all their arguments is that utility classes are not proper objects; therefore, they don’t fit into object-oriented world. They were inherited from procedural programming, mostly because we were used to a functional decomposition paradigm back then.</p><p>Assuming you agree with the arguments and want to stop using utility classes, I’ll show by example how these creatures can be replaced with proper objects.</p><h2 id="procedural-example">Procedural Example</h2><p>Say, for instance, you want to read a text file, split it into lines, trim every line and then save the results in another file. This is can be done with FileUtils from Apache Commons:</p>
    <pre>void transform(File in, File out) { Collection<String> src = FileUtils.readLines(in, "UTF-8"); Collection<String> dest = new ArrayList<>(src.size()); for (String line : src) { dest.add(line.trim()); } FileUtils.writeLines(out, dest, "UTF-8"); }</pre>
    <p>The above code may look clean; however, this is procedural programming, not object-oriented. We are manipulating data (bytes and bits) and explicitly instructing the computer from where to retrieve them and then where to put them on every single line of code. We’re defining a procedure of execution.</p><h2 id="object-oriented-alternative">Object-Oriented Alternative</h2><p>In an object-oriented paradigm, we should instantiate and compose objects, thus letting them manage data when and how they desire. Instead of calling supplementary static functions, we should create objects that are capable of exposing the behavior we are seeking:</p>
    <pre>public class Max implements Number { private final int a; private final int b; public Max(int x, int y) { this.a = x; this.b = y; } @Override public int intValue() { return this.a > this.b ? this.a : this.b; } }</pre>
    <p>This procedural call:</p>
    <pre>int max = NumberUtils.max(10, 5);</pre>
    <p>Will become object-oriented:</p>
    <pre>int max = new Max(10, 5).intValue();</pre>
    <p>Potato, potato? Not really; just read on…</p><h2 id="objects-instead-of-data-structures">Objects Instead of Data Structures</h2><p>This is how I would design the same file-transforming functionality as above but in an object-oriented manner:</p>
    <pre>void transform(File in, File out) { Collection<String> src = new Trimmed( new FileLines(new UnicodeFile(in)) ); Collection<String> dest = new FileLines( new UnicodeFile(out) ); dest.addAll(src); }</pre>
    <p>FileLines implements Collection<String> and encapsulates all file reading and writing operations. An instance of FileLines behaves exactly as a collection of strings and hides all I/O operations. When we iterate it—a file is being read. When we addAll() to it—a file is being written.</p><p>Trimmed also implements Collection<String> and encapsulates a collection of strings (Decorator pattern). Every time the next line is retrieved, it gets trimmed.</p><p>All classes taking participation in the snippet are rather small: Trimmed, FileLines, and UnicodeFile. Each of them is responsible for its own single feature, thus following perfectly the single responsibility principle.</p><aside class="youtube"> <div class="box"> YouTube video #D0dqC_3Bch8<div class="play"></div></div><div>Objects vs. Static Methods (webinar #1); 8 April 2015.</div></aside><p>On our side, as users of the library, this may be not so important, but for their developers it is an imperative. It is much easier to develop, maintain and unit-test class FileLines rather than using a readLines() method in a 80+ methods and 3000 lines utility class FileUtils. Seriously, look at its source code.</p><p>An object-oriented approach enables lazy execution. The in file is not read until its data is required. If we fail to open out due to some I/O error, the first file won’t even be touched. The whole show starts only after we call addAll().</p><p>All lines in the second snippet, except the last one, instantiate and compose smaller objects into bigger ones. This object composition is rather cheap for the CPU since it doesn’t cause any data transformations.</p><p>Besides that, it is obvious that the second script runs in O(1) space, while the first one executes in O(n). This is the consequence of our procedural approach to data in the first script.</p><p>In an object-oriented world, there is no data; there are only objects and their behavior!</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>A utility class (aka helper class) is a “structure” that has only static methods and encapsulates no state. StringUtils, IOUtils, FileUtils from Apache Commons; Iterables and Iterators from Guava, and Files from JDK7 are perfect examples of utility classes.</p><p>This design idea is very popular in the Java world (as well as C#, Ruby, etc.) because utility classes provide common functionality used everywhere.</p><aside class="youtube"> <div class="box"> YouTube video #psrp3TtaYYI<div class="play"></div></div><div>What’s Wrong About Utility Classes? (webinar #6); 2 September 2015.</div></aside><p>Here, we want to follow the DRY principle and avoid duplication. Therefore, we place common code blocks into utility classes and reuse them when necessary:</p>
    <pre>// This is a terrible design, don't reuse public class NumberUtils { public static int max(int a, int b) { return a > b ? a : b; } }</pre>
    <p>Indeed, this a very convenient technique!?</p><h2 id="utility-classes-are-evil">Utility Classes Are Evil</h2><p>However, in an object-oriented world, utility classes are considered a very bad (some even may say “terrible”) practice.</p><p>There have been many discussions of this subject; to name a few: Are Helper Classes Evil? by Nick Malik, Why helper, singletons and utility classes are mostly bad by Simon Hart, Avoiding Utility Classes by Marshal Ward, Kill That Util Class! by Dhaval Dalal, Helper Classes Are A Code Smell by Rob Bagby.</p><p>Additionally, there are a few questions on StackExchange about utility classes: If a “Utilities” class is evil, where do I put my generic code?, Utility Classes are Evil.</p><p>A dry summary of all their arguments is that utility classes are not proper objects; therefore, they don’t fit into object-oriented world. They were inherited from procedural programming, mostly because we were used to a functional decomposition paradigm back then.</p><p>Assuming you agree with the arguments and want to stop using utility classes, I’ll show by example how these creatures can be replaced with proper objects.</p><h2 id="procedural-example">Procedural Example</h2><p>Say, for instance, you want to read a text file, split it into lines, trim every line and then save the results in another file. This is can be done with FileUtils from Apache Commons:</p>
    <pre>void transform(File in, File out) { Collection<String> src = FileUtils.readLines(in, "UTF-8"); Collection<String> dest = new ArrayList<>(src.size()); for (String line : src) { dest.add(line.trim()); } FileUtils.writeLines(out, dest, "UTF-8"); }</pre>
    <p>The above code may look clean; however, this is procedural programming, not object-oriented. We are manipulating data (bytes and bits) and explicitly instructing the computer from where to retrieve them and then where to put them on every single line of code. We’re defining a procedure of execution.</p><h2 id="object-oriented-alternative">Object-Oriented Alternative</h2><p>In an object-oriented paradigm, we should instantiate and compose objects, thus letting them manage data when and how they desire. Instead of calling supplementary static functions, we should create objects that are capable of exposing the behavior we are seeking:</p>
    <pre>public class Max implements Number { private final int a; private final int b; public Max(int x, int y) { this.a = x; this.b = y; } @Override public int intValue() { return this.a > this.b ? this.a : this.b; } }</pre>
    <p>This procedural call:</p>
    <pre>int max = NumberUtils.max(10, 5);</pre>
    <p>Will become object-oriented:</p>
    <pre>int max = new Max(10, 5).intValue();</pre>
    <p>Potato, potato? Not really; just read on…</p><h2 id="objects-instead-of-data-structures">Objects Instead of Data Structures</h2><p>This is how I would design the same file-transforming functionality as above but in an object-oriented manner:</p>
    <pre>void transform(File in, File out) { Collection<String> src = new Trimmed( new FileLines(new UnicodeFile(in)) ); Collection<String> dest = new FileLines( new UnicodeFile(out) ); dest.addAll(src); }</pre>
    <p>FileLines implements Collection<String> and encapsulates all file reading and writing operations. An instance of FileLines behaves exactly as a collection of strings and hides all I/O operations. When we iterate it—a file is being read. When we addAll() to it—a file is being written.</p><p>Trimmed also implements Collection<String> and encapsulates a collection of strings (Decorator pattern). Every time the next line is retrieved, it gets trimmed.</p><p>All classes taking participation in the snippet are rather small: Trimmed, FileLines, and UnicodeFile. Each of them is responsible for its own single feature, thus following perfectly the single responsibility principle.</p><aside class="youtube"> <div class="box"> YouTube video #D0dqC_3Bch8<div class="play"></div></div><div>Objects vs. Static Methods (webinar #1); 8 April 2015.</div></aside><p>On our side, as users of the library, this may be not so important, but for their developers it is an imperative. It is much easier to develop, maintain and unit-test class FileLines rather than using a readLines() method in a 80+ methods and 3000 lines utility class FileUtils. Seriously, look at its source code.</p><p>An object-oriented approach enables lazy execution. The in file is not read until its data is required. If we fail to open out due to some I/O error, the first file won’t even be touched. The whole show starts only after we call addAll().</p><p>All lines in the second snippet, except the last one, instantiate and compose smaller objects into bigger ones. This object composition is rather cheap for the CPU since it doesn’t cause any data transformations.</p><p>Besides that, it is obvious that the second script runs in O(1) space, while the first one executes in O(n). This is the consequence of our procedural approach to data in the first script.</p><p>In an object-oriented world, there is no data; there are only objects and their behavior!</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> Typical Mistakes in Java Code </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/04/27/typical-mistakes-in-java-code.html>12 Best</li> <li /2014/04/27/typical-mistakes-in-java-code.html>All 292</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Webinars</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Talks</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Books</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Papers</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Pets</li> <li /2014/04/27/typical-mistakes-in-java-code.html class=”highlighted”>Trainings</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Award</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Testimonials</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Shift-M</li> <li /2014/04/27/typical-mistakes-in-java-code.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">Typical Mistakes in Java Code</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><ul class="unprintable subline"> <li>Translated:</li> <li>Chinese</li> <li>add yours!</li></ul><p class="unprintable"><p>This page contains most typical mistakes I see in the Java code of people working with me. Static analysis (we’re using qulice can’t catch all of the mistakes for obvious reasons, and that’s why I decided to list them all here.</p><p>Let me know if you want to see something else added here, and I’ll be happy to oblige.</p><aside class="youtube"> <div class="box"> YouTube video #9yjtsCK6Wdk<div class="play"></div></div><div>A Few Thoughts About Constructors in OOP (webinar #7); 7 October 2015.</div></aside><p>All of the listed mistakes are related to object-oriented programming in general and to Java in particular.</p><h2 id="class-names">Class Names</h2><p>Your class should be an abstraction of a real life entity with no “validators,” “controllers,” “managers,” etc. If your class name ends with an “-er”—it’s a bad design. BTW, here are my seven virtues of a good object. Also, this post explains this idea in more details: Don’t Create Objects That End With -ER.</p><p>And, of course, utility classes are anti-patterns, like StringUtils, FileUtils, and IOUtils from Apache. The above are perfect examples of terrible designs. Read this follow up post: OOP Alternative to Utility Classes</p><p>Of course, never add suffixes or prefixes to distinguish between interfaces and classes. For example, all of these names are terribly wrong: IRecord, IfaceEmployee, or RecordInterface. Usually, interface name is the name of a real-life entity, while class name should explain its implementation details. If there is nothing specific to say about an implementation, name it Default, Simple, or something similar. For example:</p><pre>class SimpleUser implements User {}; class DefaultRecord implements Record {}; class Suffixed implements Name {}; class Validated implements Content {}; </pre><h2 id="method-names">Method Names</h2><p>Methods can either return something or return void. If a method returns something, then its name should explain what it returns, for example (don’t use the get prefix ever):</p><pre>boolean isValid(String name); String content(); int ageOf(File file); </pre><p>If it returns void, then its name should explain what it does. For example:</p><pre>void save(File file); void process(Work work); void append(File file, String line); </pre><p>You can read more about this idea in Elegant Objects book, section 2.4. There is only one exception to the rule just mentioned—test methods for JUnit. They are explained below.</p><h2 id="test-method-names">Test Method Names</h2><p>Method names in JUnit tests should be created as English sentences without spaces. It’s easier to explain by example:</p><pre>/**
  • HttpRequest can return its content in Unicode.
  • @throws Exception If test fails */ @Test public void returnsItsContentInUnicode() throws Exception { } </code></pre><p>It’s important to start the first sentence of your Javadoc with the name of the class you’re testing followed by can (or cannot). So, your first sentence should always be similar to “somebody can do something.”</p><p>The method name will state exactly the same, but without the subject. If I add a subject at the beginning of the method name, I should get a complete English sentence, as in above example: “HttpRequest returns its content in Unicode.”</p><p>Pay attention that the test method doesn’t start with can. Only Javadoc comments use ‘can.’</p><p>It’s a good practice to always declare test methods as throwing Exception.</p><h2 id="variable-names">Variable Names</h2><p>Avoid composite names of variables, like timeOfDay, firstItem, or httpRequest. I mean with both—class variables and in-method ones. A variable name should be long enough to avoid ambiguity in its scope of visibility, but not too long if possible. A name should be a noun in singular or plural form, or an appropriate abbreviation. More about it in this post: A Compound Name Is a Code Smell. For example:</p><pre>List<String> names; void sendThroughProxy(File file, Protocol proto); private File content; public HttpRequest request; </pre><p>Sometimes, you may have collisions between constructor parameters and in-class properties if the constructor saves incoming data in an instantiated object. In this case, I recommend to create abbreviations by removing vowels (see how USPS abbreviates street names).</p><p>Another example:</p><pre>public class Message { private String recipient; public Message(String rcpt) { this.recipient = rcpt; } } </pre><p>In many cases, the best hint for a name of a variable can ascertained by reading its class name. Just write it with a small letter, and you should be good:</p><pre>File file; User user; Branch branch; </pre><p>However, never do the same for primitive types, like Integer number or String string.</p><p>You can also use an adjective, when there are multiple variables with different characteristics. For instance:</p><pre>String contact(String left, String right); </pre><h2 id="constructors">Constructors</h2><p>Without exceptions, there should be only one constructor that stores data in object variables. All other constructors should call this one with different arguments. For example:</p><pre>public class Server { private String address; public Server(String uri) { this.address = uri; } public Server(URI uri) { this(uri.toString()); } } </pre><p>More about it in There Can Be Only One Primary Constructor.</p><h2 id="one-time-variables">One-time Variables</h2><p>Avoid one-time variables at all costs. By “one-time” I mean variables that are used only once. Like in this example:</p><pre>String name = "data.txt"; return new File(name); </pre><p>This above variable is used only once and the code should be refactored to:</p><pre>return new File("data.txt"); </pre><p>Sometimes, in very rare cases—mostly because of better formatting—one-time variables may be used. Nevertheless, try to avoid such situations at all costs.</p><h2 id="exceptions">Exceptions</h2><p>Needless to say, you should never swallow exceptions, but rather let them bubble up as high as possible. Private methods should always let checked exceptions go out.</p><p>Never use exceptions for flow control. For example this code is wrong:</p><pre>int size; try { size = this.fileSize(); } catch (IOException ex) { size = 0; } </pre><p>Seriously, what if that IOException says “disk is full?” Will you still assume that the size of the file is zero and move on?</p><h2 id="indentation">Indentation</h2><p>For indentation, the main rule is that a bracket should either end a line or be closed on the same line (reverse rule applies to a closing bracket). For example, the following is not correct because the first bracket is not closed on the same line and there are symbols after it. The second bracket is also in trouble because there are symbols in front of it and it is not opened on the same line:</p><pre>final File file = new File(directory, "file.txt"); </pre><p>Correct indentation should look like:</p><pre>StringUtils.join( Arrays.asList( "first line", "second line", StringUtils.join( Arrays.asList("a", "b") ) ), "separator" ); </pre><p>The second important rule of indentation says that you should put as much as possible on one line - within the limit of 80 characters. The example above is not valid since it can be compacted:</p><pre>StringUtils.join( Arrays.asList( "first line", "second line", StringUtils.join(Arrays.asList("a", "b")) ), "separator" ); </pre><h2 id="redundant-constants">Redundant Constants</h2><p>Class constants should be used when you want to share information between class methods, and this information is a characteristic (!) of your class. Don’t use constants as a replacement of string or numeric literals—very bad practice that leads to code pollution. Constants (as with any object in OOP) should have a meaning in a real world. What meaning do these constants have in the real world:</p><pre>class Document { private static final String D_LETTER = "D"; // bad practice private static final String EXTENSION = ".doc"; // good practice } </pre><p>Another typical mistake is to use constants in unit tests to avoid duplicate string/numeric literals in test methods. Don’t do this! Every test method should work with its own set of input values.</p><p>Use new texts and numbers in every new test method. They are independent. So, why do they have to share the same input constants?</p><h2 id="test-data-coupling">Test Data Coupling</h2><p>This is an example of data coupling in a test method:</p><pre>User user = new User("Jeff"); // maybe some other code here MatcherAssert.assertThat(user.name(), Matchers.equalTo("Jeff")); </pre><p>On the last line, we couple "Jeff" with the same string literal from the first line. If, a few months later, someone wants to change the value on the third line, he/she has to spend extra time finding where else "Jeff" is used in the same method.</p><p>To avoid this data coupling, you should introduce a variable. More about it here: A Few Thoughts on Unit Test Scaffolding.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div ><p>This page contains most typical mistakes I see in the Java code of people working with me. Static analysis (we’re using qulice can’t catch all of the mistakes for obvious reasons, and that’s why I decided to list them all here.</p><p>Let me know if you want to see something else added here, and I’ll be happy to oblige.</p><aside class="youtube"> <div class="box"> YouTube video #9yjtsCK6Wdk<div class="play"></div></div><div>A Few Thoughts About Constructors in OOP (webinar #7); 7 October 2015.</div></aside><p>All of the listed mistakes are related to object-oriented programming in general and to Java in particular.</p><h2 id="class-names">Class Names</h2><p>Your class should be an abstraction of a real life entity with no “validators,” “controllers,” “managers,” etc. If your class name ends with an “-er”—it’s a bad design. BTW, here are my seven virtues of a good object. Also, this post explains this idea in more details: Don’t Create Objects That End With -ER.</p><p>And, of course, utility classes are anti-patterns, like StringUtils, FileUtils, and IOUtils from Apache. The above are perfect examples of terrible designs. Read this follow up post: OOP Alternative to Utility Classes</p><p>Of course, never add suffixes or prefixes to distinguish between interfaces and classes. For example, all of these names are terribly wrong: IRecord, IfaceEmployee, or RecordInterface. Usually, interface name is the name of a real-life entity, while class name should explain its implementation details. If there is nothing specific to say about an implementation, name it Default, Simple, or something similar. For example:</p><pre>class SimpleUser implements User {}; class DefaultRecord implements Record {}; class Suffixed implements Name {}; class Validated implements Content {}; </pre><h2 id="method-names">Method Names</h2><p>Methods can either return something or return void. If a method returns something, then its name should explain what it returns, for example (don’t use the get prefix ever):</p><pre>boolean isValid(String name); String content(); int ageOf(File file); </pre><p>If it returns void, then its name should explain what it does. For example:</p><pre>void save(File file); void process(Work work); void append(File file, String line); </pre><p>You can read more about this idea in Elegant Objects book, section 2.4. There is only one exception to the rule just mentioned—test methods for JUnit. They are explained below.</p><h2 id="test-method-names">Test Method Names</h2><p>Method names in JUnit tests should be created as English sentences without spaces. It’s easier to explain by example:</p><pre>/**
  • HttpRequest can return its content in Unicode.
  • @throws Exception If test fails */ @Test public void returnsItsContentInUnicode() throws Exception { } </code></pre><p>It’s important to start the first sentence of your Javadoc with the name of the class you’re testing followed by can (or cannot). So, your first sentence should always be similar to “somebody can do something.”</p><p>The method name will state exactly the same, but without the subject. If I add a subject at the beginning of the method name, I should get a complete English sentence, as in above example: “HttpRequest returns its content in Unicode.”</p><p>Pay attention that the test method doesn’t start with can. Only Javadoc comments use ‘can.’</p><p>It’s a good practice to always declare test methods as throwing Exception.</p><h2 id="variable-names">Variable Names</h2><p>Avoid composite names of variables, like timeOfDay, firstItem, or httpRequest. I mean with both—class variables and in-method ones. A variable name should be long enough to avoid ambiguity in its scope of visibility, but not too long if possible. A name should be a noun in singular or plural form, or an appropriate abbreviation. More about it in this post: A Compound Name Is a Code Smell. For example:</p><pre>List<String> names; void sendThroughProxy(File file, Protocol proto); private File content; public HttpRequest request; </pre><p>Sometimes, you may have collisions between constructor parameters and in-class properties if the constructor saves incoming data in an instantiated object. In this case, I recommend to create abbreviations by removing vowels (see how USPS abbreviates street names).</p><p>Another example:</p><pre>public class Message { private String recipient; public Message(String rcpt) { this.recipient = rcpt; } } </pre><p>In many cases, the best hint for a name of a variable can ascertained by reading its class name. Just write it with a small letter, and you should be good:</p><pre>File file; User user; Branch branch; </pre><p>However, never do the same for primitive types, like Integer number or String string.</p><p>You can also use an adjective, when there are multiple variables with different characteristics. For instance:</p><pre>String contact(String left, String right); </pre><h2 id="constructors">Constructors</h2><p>Without exceptions, there should be only one constructor that stores data in object variables. All other constructors should call this one with different arguments. For example:</p><pre>public class Server { private String address; public Server(String uri) { this.address = uri; } public Server(URI uri) { this(uri.toString()); } } </pre><p>More about it in There Can Be Only One Primary Constructor.</p><h2 id="one-time-variables">One-time Variables</h2><p>Avoid one-time variables at all costs. By “one-time” I mean variables that are used only once. Like in this example:</p><pre>String name = "data.txt"; return new File(name); </pre><p>This above variable is used only once and the code should be refactored to:</p><pre>return new File("data.txt"); </pre><p>Sometimes, in very rare cases—mostly because of better formatting—one-time variables may be used. Nevertheless, try to avoid such situations at all costs.</p><h2 id="exceptions">Exceptions</h2><p>Needless to say, you should never swallow exceptions, but rather let them bubble up as high as possible. Private methods should always let checked exceptions go out.</p><p>Never use exceptions for flow control. For example this code is wrong:</p><pre>int size; try { size = this.fileSize(); } catch (IOException ex) { size = 0; } </pre><p>Seriously, what if that IOException says “disk is full?” Will you still assume that the size of the file is zero and move on?</p><h2 id="indentation">Indentation</h2><p>For indentation, the main rule is that a bracket should either end a line or be closed on the same line (reverse rule applies to a closing bracket). For example, the following is not correct because the first bracket is not closed on the same line and there are symbols after it. The second bracket is also in trouble because there are symbols in front of it and it is not opened on the same line:</p><pre>final File file = new File(directory, "file.txt"); </pre><p>Correct indentation should look like:</p><pre>StringUtils.join( Arrays.asList( "first line", "second line", StringUtils.join( Arrays.asList("a", "b") ) ), "separator" ); </pre><p>The second important rule of indentation says that you should put as much as possible on one line - within the limit of 80 characters. The example above is not valid since it can be compacted:</p><pre>StringUtils.join( Arrays.asList( "first line", "second line", StringUtils.join(Arrays.asList("a", "b")) ), "separator" ); </pre><h2 id="redundant-constants">Redundant Constants</h2><p>Class constants should be used when you want to share information between class methods, and this information is a characteristic (!) of your class. Don’t use constants as a replacement of string or numeric literals—very bad practice that leads to code pollution. Constants (as with any object in OOP) should have a meaning in a real world. What meaning do these constants have in the real world:</p><pre>class Document { private static final String D_LETTER = "D"; // bad practice private static final String EXTENSION = ".doc"; // good practice } </pre><p>Another typical mistake is to use constants in unit tests to avoid duplicate string/numeric literals in test methods. Don’t do this! Every test method should work with its own set of input values.</p><p>Use new texts and numbers in every new test method. They are independent. So, why do they have to share the same input constants?</p><h2 id="test-data-coupling">Test Data Coupling</h2><p>This is an example of data coupling in a test method:</p><pre>User user = new User("Jeff"); // maybe some other code here MatcherAssert.assertThat(user.name(), Matchers.equalTo("Jeff")); </pre><p>On the last line, we couple "Jeff" with the same string literal from the first line. If, a few months later, someone wants to change the value on the third line, he/she has to spend extra time finding where else "Jeff" is used in the same method.</p><p>To avoid this data coupling, you should introduce a variable. More about it here: A Few Thoughts on Unit Test Scaffolding.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US" itemscope="" itemtype="http://schema.org/WebSite"> <head> How Much Do You Pay Per Line of Code? </head> <body><div class="wrapper"> <aside class="header-toggle unprintable" id="header-toggle" title="Show the menu" onclick="$('#header').show();$('#header-toggle').hide();">☰</aside> <header class="header" id="header"><div class="face"> Subscribe Yegor Bugayenko </div><nav><ul class="menu social notranslate"> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li> <li></li></ul><ul class="menu"> <li>Home</li> <li /2014/04/11/cost-of-loc.html>12 Best</li> <li /2014/04/11/cost-of-loc.html>All 292</li> <li /2014/04/11/cost-of-loc.html>Webinars</li> <li /2014/04/11/cost-of-loc.html>Talks</li> <li /2014/04/11/cost-of-loc.html>Books</li> <li /2014/04/11/cost-of-loc.html>Papers</li> <li /2014/04/11/cost-of-loc.html>Pets</li> <li /2014/04/11/cost-of-loc.html class=”highlighted”>Trainings</li> <li /2014/04/11/cost-of-loc.html>Award</li> <li /2014/04/11/cost-of-loc.html>Testimonials</li> <li /2014/04/11/cost-of-loc.html>Shift-M</li> <li /2014/04/11/cost-of-loc.html>Paintings</li> <li>По-русски</li></ul></nav><div class="search"> <form method="get" action="https://www.google.com/search" itemprop="potentialAction" itemscope="" itemtype="http://schema.org/SearchAction"> </form></div><div class="hot"><ul></ul></div></header></div><section itemscope="" itemtype="http://schema.org/BlogPosting"><div class="wrapper"> <header><p class="printable"> QR code</p><p class="printable"> </p><h1 itemprop="name headline mainEntityOfPage">How Much Do You Pay Per Line of Code?</h1><ul class="subline"> <li> </li> <li class="printable" itemscope="" itemprop="author" itemtype="http://schema.org/Person"> Yegor Bugayenko </li> <li class="unprintable"> comments </li></ul><p class="unprintable">
    badge
    <p>Yes, I know, “line of code” (LoC) is a very wrong metric. There are tons of articles written about it, as well as famous books. However, I want to compare two projects in which I have participated recently and discuss some very interesting numbers.</p><aside class="youtube"> <div class="box"> YouTube video #qRZYJGYdrwk<div class="play"></div></div><div>XDSD: management without meetings; 13 February 2016.</div></aside><h2 id="project-1-traditionally-co-located">Project #1: Traditionally Co-located</h2><p>The first project I was a part of was performed by a traditionally co-located group of programmers. There were about 20 of them (I’m not counting managers, analysts, product owners, SCRUM masters, etc.) The project was a web auctioning site with pretty high traffic numbers (over two million page views per day).</p><p>The code base size was about 200k lines, of which 150k was PHP, 35k JavaScript and the remainder CSS, XML, Ruby, and something else. I’m counting only non-empty and non-comment lines of code, using cloc.pl.</p><p>It was a commercial project, so I can’t disclose its name.</p>
    Brazil (1985) by Terry Gilliam<figcaption id="51e79012">Brazil (1985) by Terry Gilliam</figcaption>
    <p>The team was co-located in one office in Europe where everybody was working “from nine ‘til five.” We had meetings, lunches, desk-to-desk chats and lots of other informal communications. All tasks were tracked in JIRA.</p><h2 id="project-2-extremely-distributed">Project #2: Extremely Distributed</h2><p>The second project was an open source Java product, developed by an extremely distributed team of about 15 developers. We didn’t have any chats or any other informal communications. We discussed everything in GitHub issues. The code base was significantly smaller with only about 30k lines, of which about 90% was Java and the rest in XML.</p>
    Shaolin Temple (1982) by Chang Hsin Yen<figcaption>Shaolin Temple (1982) by Chang Hsin Yen</figcaption>
    <h2 id="maturity-of-development">Maturity of Development</h2><p>Both projects hosted their code bases on GitHub. Both teams were developing in feature branches- even for small fixes.</p><p>Both teams used build automation, continuous integration, pre-flight builds, static analysis and code reviews. This indicates the maturity of the project teams.</p><p>Both projects satisfied the requirements of their users. I’m mentioning this to emphasize that both projects produced valuable and useful lines of code. There was no garbage and almost no code duplication.</p><h2 id="show-me-the-money">Show Me the Money</h2><p>In both projects, my role was called that of lead architect, and I knew their financial details. Besides that, I had access to both Git repositories, so I can measure how many new lines (or changed lines) were introduced by both teams in, say, a three-month period.</p><p>Now, let’s see the numbers.</p><p>The first project (the one that was co-located) was paying approximately €50,000 annually to a good developer, which was about $5,600 per month or $35 per hour. The second one (the extremely distributed project) was paying $20-35 per hour, for completed tasks only according to one of the principles of XDSD.</p><p>The first one, in three months, produced 59k new lines and removed 29k in changes in the master branch, which totals 88k lines of code. The project resulted in about 10,000 man hours to produce these lines (20 programmers, three months, 170 working hours per month)—which equates to about $350k. Therefore, the project cost a whopping</p><p class="red center em2">$3.98 per line</p><p>The second project, in the same three month period, produced 45k new lines and removed 9k, which comes to 54k in all. To complete this work, we spent only $7k (approximately 350 working hours in 650 tasks). Thus, the project cost merely:</p><p class="green center em2">¢13 per line</p><p>This also means that programmers were writing approximately 150 lines per hour or over a thousand per day. The Mythical Man-Month talks about 10 lines per day, which is a hundred times less than we saw in our project.</p><p>$350k vs $7k, $3.98 vs ¢13? What do you think?</p><h2 id="how-to-validate-the-numbers">How to Validate the Numbers?</h2><p>If you’re curious, I’m using hoc to get the numbers from Git (it is explained in Hits-of-Code Instead of SLoC). You can validate the numbers for the second project here on GitHub: jcabi/jcabi-github.</p><h2 id="conclusion">Conclusion</h2><p>What I’m trying to express with these numbers is that distributed programming is much more effective, money-wise, than a co-located team. Again, I can hear you saying that “line of code” is not a proper metric. But, come on, $0.13 vs. $3.98? Thirty times more expensive?</p>
    The Big Lebowski (1998) by Joel Coen<figcaption>The Big Lebowski (1998) by Joel Coen</figcaption>
    <p>It’s not about metrics any more. It’s about preventing wasteful man hours and the huge waste of money that comes with them?</p><h2 id="can-we-do-the-same">Can We Do the Same?</h2><p>Of course, the same results can’t be achieved by just telling your programmers to work from home and never come to the office. XDSD is not about that. XDSD is about strict quality principles, which should be followed by the entire team.</p><p>And when these principles are in place—you pay thirty times less.</p><p>By the way, this is what people say about their projects:</p><ul> <li>$12–103: crazyontap.com</li> <li>$15–40: betterembsw.blogspot.nl</li> <li>over $5: joelonsoftware.com</li></ul><p>What are your numbers? Please post your comments below.</p></p><nav class="buttons notranslate desktop-only"> 0 0 0 0 0 0 </nav> </header> <article class="main" itemprop="articleBody"><div >
    badge
    <p>Yes, I know, “line of code” (LoC) is a very wrong metric. There are tons of articles written about it, as well as famous books. However, I want to compare two projects in which I have participated recently and discuss some very interesting numbers.</p><aside class="youtube"> <div class="box"> YouTube video #qRZYJGYdrwk<div class="play"></div></div><div>XDSD: management without meetings; 13 February 2016.</div></aside><h2 id="project-1-traditionally-co-located">Project #1: Traditionally Co-located</h2><p>The first project I was a part of was performed by a traditionally co-located group of programmers. There were about 20 of them (I’m not counting managers, analysts, product owners, SCRUM masters, etc.) The project was a web auctioning site with pretty high traffic numbers (over two million page views per day).</p><p>The code base size was about 200k lines, of which 150k was PHP, 35k JavaScript and the remainder CSS, XML, Ruby, and something else. I’m counting only non-empty and non-comment lines of code, using cloc.pl.</p><p>It was a commercial project, so I can’t disclose its name.</p>
    Brazil (1985) by Terry Gilliam<figcaption id="51e79012">Brazil (1985) by Terry Gilliam</figcaption>
    <p>The team was co-located in one office in Europe where everybody was working “from nine ‘til five.” We had meetings, lunches, desk-to-desk chats and lots of other informal communications. All tasks were tracked in JIRA.</p><h2 id="project-2-extremely-distributed">Project #2: Extremely Distributed</h2><p>The second project was an open source Java product, developed by an extremely distributed team of about 15 developers. We didn’t have any chats or any other informal communications. We discussed everything in GitHub issues. The code base was significantly smaller with only about 30k lines, of which about 90% was Java and the rest in XML.</p>
    Shaolin Temple (1982) by Chang Hsin Yen<figcaption>Shaolin Temple (1982) by Chang Hsin Yen</figcaption>
    <h2 id="maturity-of-development">Maturity of Development</h2><p>Both projects hosted their code bases on GitHub. Both teams were developing in feature branches- even for small fixes.</p><p>Both teams used build automation, continuous integration, pre-flight builds, static analysis and code reviews. This indicates the maturity of the project teams.</p><p>Both projects satisfied the requirements of their users. I’m mentioning this to emphasize that both projects produced valuable and useful lines of code. There was no garbage and almost no code duplication.</p><h2 id="show-me-the-money">Show Me the Money</h2><p>In both projects, my role was called that of lead architect, and I knew their financial details. Besides that, I had access to both Git repositories, so I can measure how many new lines (or changed lines) were introduced by both teams in, say, a three-month period.</p><p>Now, let’s see the numbers.</p><p>The first project (the one that was co-located) was paying approximately €50,000 annually to a good developer, which was about $5,600 per month or $35 per hour. The second one (the extremely distributed project) was paying $20-35 per hour, for completed tasks only according to one of the principles of XDSD.</p><p>The first one, in three months, produced 59k new lines and removed 29k in changes in the master branch, which totals 88k lines of code. The project resulted in about 10,000 man hours to produce these lines (20 programmers, three months, 170 working hours per month)—which equates to about $350k. Therefore, the project cost a whopping</p><p class="red center em2">$3.98 per line</p><p>The second project, in the same three month period, produced 45k new lines and removed 9k, which comes to 54k in all. To complete this work, we spent only $7k (approximately 350 working hours in 650 tasks). Thus, the project cost merely:</p><p class="green center em2">¢13 per line</p><p>This also means that programmers were writing approximately 150 lines per hour or over a thousand per day. The Mythical Man-Month talks about 10 lines per day, which is a hundred times less than we saw in our project.</p><p>$350k vs $7k, $3.98 vs ¢13? What do you think?</p><h2 id="how-to-validate-the-numbers">How to Validate the Numbers?</h2><p>If you’re curious, I’m using hoc to get the numbers from Git (it is explained in Hits-of-Code Instead of SLoC). You can validate the numbers for the second project here on GitHub: jcabi/jcabi-github.</p><h2 id="conclusion">Conclusion</h2><p>What I’m trying to express with these numbers is that distributed programming is much more effective, money-wise, than a co-located team. Again, I can hear you saying that “line of code” is not a proper metric. But, come on, $0.13 vs. $3.98? Thirty times more expensive?</p>
    The Big Lebowski (1998) by Joel Coen<figcaption>The Big Lebowski (1998) by Joel Coen</figcaption>
    <p>It’s not about metrics any more. It’s about preventing wasteful man hours and the huge waste of money that comes with them?</p><h2 id="can-we-do-the-same">Can We Do the Same?</h2><p>Of course, the same results can’t be achieved by just telling your programmers to work from home and never come to the office. XDSD is not about that. XDSD is about strict quality principles, which should be followed by the entire team.</p><p>And when these principles are in place—you pay thirty times less.</p><p>By the way, this is what people say about their projects:</p><ul> <li>$12–103: crazyontap.com</li> <li>$15–40: betterembsw.blogspot.nl</li> <li>over $5: joelonsoftware.com</li></ul><p>What are your numbers? Please post your comments below.</p></div></article></div><div class="wrapper"> </div><div class="disqus" role="complementary"><p class="disqus_hint"> Please, use syntax highlighting in your comments, to make them more readable.</p><div id="disqus_thread" class="disqus-thread">  </div> </div><div class="wrapper"> <footer class="footer"><p> © Yegor Bugayenko 2014–2018</p></footer></div></section><div class="wrapper unprintable" style="text-align:center;margin-top:2em;"> sixnines availability badge </div> </body> </html>
sixnines availability badge